10 Common YAML Syntax Errors and How to Fix Them

YAML is a popular data format used in configuration files for tools such as Docker, Kubernetes, GitHub Actions, and many other applications. Its simple structure makes configuration easy to read, but small syntax mistakes can cause parsing errors or unexpected behavior. If your YAML file is not working correctly, the problem may be caused by indentation, missing colons, incorrect data types, or other common mistakes. In this guide, we will explore 10 common YAML syntax errors and explain how to fix them with practical examples.

1. Incorrect Indentation

YAML uses indentation to represent relationships between keys and values. Incorrect indentation can make a valid structure invalid.

Incorrect YAML:

server:
  host: localhost
 port: 3000

Correct YAML:

server:
  host: localhost
  port: 3000

How to fix it: Keep related properties at the same indentation level. Use spaces instead of tabs.

2. Using Tabs Instead of Spaces

YAML does not allow tab characters for indentation. Using tabs may cause a parser error.

Incorrect YAML:

database:
	host: localhost

Correct YAML:

database:
  host: localhost

How to fix it: Configure your code editor to insert spaces when you press the Tab key.

3. Missing Colons

A colon separates a key from its value. Forgetting it can make the document invalid.

Incorrect YAML:

name John
version 1.0

Correct YAML:

name: John
version: "1.0"

How to fix it: Use a colon after every mapping key. Quote version numbers when you want to preserve them as strings.

4. Incorrect List Formatting

YAML represents lists using a hyphen followed by a space. Missing spaces or inconsistent indentation can break list formatting.

Incorrect YAML:

languages:
  - JavaScript
  -Python
  - Java

Correct YAML:

languages:
  - JavaScript
  - Python
  - Java

How to fix it: Start every list item with - and keep list items aligned.

5. Forgetting Quotes Around Special Characters

Some characters have special meanings in YAML. For example, # can introduce a comment, while : followed by whitespace can separate a key from a value.

Incorrect YAML:

message: Hello: developer

Correct YAML:

message: "Hello: developer"

How to fix it: Quote strings containing characters that could be interpreted as YAML syntax.

6. Incorrect Boolean Values

YAML supports Boolean values, but their interpretation can depend on the YAML version and parser.

Example:

enabled: true
debug: false

These are Boolean values, not strings.

If your application expects text instead, use quotes:

enabled: "true"
debug: "false"

How to fix it: Understand whether your application expects a Boolean or a string. Prefer true and false for Boolean values in YAML 1.2.

7. Incorrect Representation of Null Values

YAML uses null or ~ to represent an empty value. However, an empty string is different from a null value.

Example:

username: null
nickname: ""

Here, username is null, while nickname is an empty string.

How to fix it: Choose the correct representation based on what your application expects.

8. Duplicate Keys

Defining the same key multiple times in a mapping can cause unexpected results. Some parsers reject duplicate keys, while others may keep only one value.

Incorrect YAML:

server:
  port: 3000
  port: 8080

Correct YAML:

server:
  port: 8080

How to fix it: Keep each key unique within the same mapping unless your specific format explicitly supports another approach.

9. Incorrect Nested Objects

Nested objects require consistent indentation so YAML can identify parent and child properties.

Incorrect YAML:

user:
  name: Sumit
    email: [email protected]

Correct YAML:

user:
  name: Sumit
  email: [email protected]

How to fix it: Align properties that belong to the same object. Indent only when creating a nested structure.

10. Invalid JSON-to-YAML Conversion

Converting JSON into YAML can introduce errors if the source JSON is invalid or if the conversion process handles data types incorrectly.

Invalid JSON:

{
  "name": "Sumit",
  "age": 25,
}

The trailing comma after 25 makes this JSON invalid.

Correct JSON:

{
  "name": "Sumit",
  "age": 25
}

How to fix it: Validate your JSON before converting it. You can use an online JSON to YAML converter to transform valid JSON into readable YAML.

How to Validate YAML Before Using It

Follow these steps to reduce configuration errors

1) Check indentation and use spaces instead of tabs.

2) Verify that every mapping key has a colon.

3) Check lists, nested objects, and special characters.

4) Confirm that values use the correct data types.

5) Validate the YAML using a reliable YAML parser before deploying it.

Conclusion

YAML syntax errors are often caused by small formatting mistakes, such as incorrect indentation, missing spaces, duplicate keys, or improperly quoted strings. These issues can prevent applications from loading configuration files correctly. By learning these 10 common mistakes, you can debug YAML files faster and avoid unnecessary development delays. When converting JSON data, validate the source first and use a reliable JSON to YAML converter to simplify the process.