YAML Common Errors and How to Fix Them

YAML is simple to read but strict about formatting. Small mistakes — an extra space, a missing colon, or a tab instead of a space — can cause parsing errors that break an entire application. This topic covers the most common YAML errors, explains why they happen, and shows how to fix each one.

Error 1 – Using Tabs Instead of Spaces

This is the most common YAML error. YAML strictly forbids tab characters for indentation. Only space characters are allowed.

Wrong (Tab used)

person:
	name: Alice    ← Tab character here causes error
	age: 28

Correct (Spaces used)

person:
  name: Alice    ← 2 spaces
  age: 28

How to fix: Configure the text editor to insert spaces instead of tabs. In VS Code, check the bottom bar for the indentation setting and switch from "Tab Size" to "Spaces".

Error 2 – Missing Space After Colon

A colon followed immediately by a character (no space) is not recognized as a key-value separator.

Wrong

name:Alice     ← No space after colon
port:8080

Correct

name: Alice    ← Space after colon
port: 8080

How to fix: Always add exactly one space after each colon in key-value pairs.

Error 3 – Inconsistent Indentation

All items at the same level must have the same number of leading spaces. Mixing 2-space and 4-space indentation at the same level causes errors.

Wrong

server:
  host: localhost
    port: 8080     ← 4 spaces instead of 2 — wrong level

Correct

server:
  host: localhost
  port: 8080       ← Both at 2 spaces — same level

How to fix: Choose a consistent indent size (2 spaces is standard) and use it throughout the entire file.

Error 4 – Colon in a String Value (Unquoted)

A colon followed by a space inside a value confuses the YAML parser. It reads everything after the colon as a new key-value pair.

Wrong

message: Error: file not found    ← Parser sees "Error" as a nested key
url: https://estudy247.com        ← The // may confuse some parsers

Correct

message: "Error: file not found"
url: "https://estudy247.com"

How to fix: Wrap any value containing a colon followed by a space inside double quotes.

Error 5 – Duplicate Keys

Defining the same key twice in the same mapping is not valid. Some parsers silently use the last value, others throw an error.

Wrong

config:
  host: localhost
  port: 8080
  host: remoteserver    ← Duplicate key 'host'

Correct

config:
  primary_host: localhost
  fallback_host: remoteserver
  port: 8080

How to fix: Use unique keys. If two values are needed for the same concept, rename them to distinguish their meaning.

Error 6 – Special Characters in Unquoted Strings

Characters like #, :, [, {, &, *, !, and | have special meaning in YAML. Using them in an unquoted value causes unexpected behavior.

Wrong

comment: Hello # World    ← # starts a comment here, value becomes "Hello"
bracket: [start           ← Broken list syntax

Correct

comment: "Hello # World"
bracket: "[start"

How to fix: Always quote strings that contain YAML special characters.

Error 7 – Wrong Boolean or Null Values

Older YAML parsers (YAML 1.1) treat values like yes, no, on, off as booleans. This is a common source of bugs when writing configuration values like country codes or on/off labels.

Problem

# In YAML 1.1 parsers:
country: NO        ← Parsed as false (boolean), not the string "NO" for Norway
power: on          ← Parsed as true, not the string "on"

Correct

country: "NO"      ← Quoted to force string type
power: "on"

How to fix: Use true / false for booleans only. Quote any value that looks like a boolean but is actually a string.

Error 8 – Missing Dash in a List

List items require a dash and a space. Missing either one breaks the list structure.

Wrong

fruits:
  apple       ← No dash — not a list item
  mango

Correct

fruits:
  - apple
  - mango

How to fix: Every list item must start with - (dash followed by a space) at the correct indentation level.

Error 9 – Indented Content After a Block Scalar

Content following a block scalar (| or >) must be indented more than the key. If the content is at the wrong indentation, YAML will not read it as part of the block.

Wrong

script: |
echo "Hello"    ← Not indented — YAML does not attach this to 'script'

Correct

script: |
  echo "Hello"  ← Indented 2 spaces under 'script'
  echo "World"

Error 10 – Forgetting the Document Separator in Multi-Document Files

When writing multiple YAML documents in one file, each document must be separated by ---. Without this, the parser either reads both as one document or fails.

Wrong

name: Alice
age: 25
name: Bob       ← Parser doesn't know this is a new document
age: 30

Correct

---
name: Alice
age: 25
---
name: Bob
age: 30

Common YAML Errors Quick Reference

Recommended YAML Validation Tools

• yamllint: Command-line tool for linting YAML files. Run yamllint filename.yaml to check for errors.
• VS Code YAML Extension: Highlights syntax errors in real time while writing.
• Online YAML Parser (yamlparser.org): Paste YAML to check if it parses correctly.
• kubectl --dry-run: Test Kubernetes YAML without actually applying it: kubectl apply -f file.yaml --dry-run=client

Summary

• The most common YAML errors involve indentation (tabs vs spaces) and missing spaces after colons
• Special characters in unquoted strings cause unexpected parsing results
• Always quote values that contain colons, hashes, or other YAML-reserved characters
• Use true/false for booleans and quote any string that resembles a boolean
• Use a YAML linter or validator to catch errors before deploying configuration files