T
yaml debugging configuration web-development devops

Solving 'YAML parse error' and common YAML Indentation issues

A comprehensive guide to fixing YAML errors like 'invalid YAML', 'indentation error', and 'tab character' issues. Learn the strict rules of YAML syntax.

2026-04-11

Solving "YAML parse error" and common YAML Indentation issues: A Complete Guide

YAML (YAML Ain't Markup Language) is loved for its human-readable format and clean syntax. It is the standard for configuration in tools like Kubernetes, Docker Compose, GitHub Actions, and many static site generators. However, YAML is notoriously strict about whitespace and indentation. One single space in the wrong place can lead to an invalid YAML or YAML parse error that is hard to track down.

In this guide, we will explore the most common YAML errors and how to fix them quickly.

1. Common YAML Error Messages

Depending on your parser (like js-yaml or Python's PyYAML), you might see:

  • YAML parse error: bad indentation of a mapping entry
  • YAML parse error: found character '\t' that cannot start any token
  • invalid YAML: mapping values are not allowed here
  • YAML parse error: duplicate key "..."
  • YAML syntax error: end of stream loss

2. Top Causes and Solutions

2.1 Indentation Errors (The #1 Killer)

YAML uses indentation to define structure (like braces {} in JSON). It must be consistent.

The Mistake:

services:
  web:
    image: nginx
   ports:  # Wrong indentation (3 spaces instead of 2 or 4)
      - "80:80"

The Solution: Ensure all siblings in a map or list have the exact same number of leading spaces. Use 2 spaces as the industry standard.

2.2 Tab Characters

YAML strictly forbids the use of the Tab character (\t) for indentation. You MUST use spaces.

The Error: found character '\t' that cannot start any token

The Solution: Configure your code editor (VS Code, Sublime, etc.) to "Convert Tabs to Spaces." If you've already pasted code with tabs, use a "Find and Replace" to swap \t with .

2.3 Duplicate Keys

Unlike some other formats, YAML does not allow the same key to appear twice at the same level of a mapping.

The Mistake:

image: nginx
ports:
  - "80:80"
image: alpine  # Duplicate key!

The Solution: Check your configuration for accidental duplicates, especially in large files or when merging multiple files.

2.4 Missing Space After Colon

A common YAML gotcha is forgetting the space after the colon (:) that separates a key and its value.

The Mistake: url:https://example.com (YAML thinks this is one long string)

The Solution: Always include a space: url: https://example.com.

2.5 Multi-line Strings

If you need to include a long string or a block of code, you must use the correct block scalar indicators: | (keeps newlines) or > (folds newlines).

The Mistake:

description: This is a
very long string
without indicators. # This will cause a parse error

The Solution:

description: |
  This is a
  very long string
  that preserves newlines.

3. Advanced Troubleshooting

3.1 Special Characters in Values

If your value contains characters like :, {, }, [, ], ,, &, *, #, ?, |, -, <, >, =, !, %, @, `, it might confuse the parser. Solution: Wrap the entire value in double quotes ("...") or single quotes ('...').

3.2 Boolean Gotchas

In YAML 1.1, values like yes, no, on, off are automatically converted to booleans (true/false). This can break things if you actually wanted the string "no" (like a country code). Solution: Always quote these strings: country: "NO".

4. Prevention and Best Practices

  1. Use a YAML Linter: Install a linter in your editor (e.g., vscode-yaml by Red Hat) to catch errors in real-time.
  2. Schema Validation: For specific formats like Kubernetes or Docker Compose, use their official JSON/YAML schemas for validation.
  3. Automated Conversion: If you are more comfortable with JSON, write your config in JSON and convert it to YAML using a tool.
  4. Consistent Spacing: Standardize on 2 spaces for all YAML files in your project.

5. FAQ: Frequently Asked Questions

Q: Why is my YAML valid in one parser but not another?

A: There are two main versions of YAML: 1.1 and 1.2. Some parsers (like PyYAML) default to 1.1, while others use 1.2. Version 1.2 is more compatible with JSON. If you encounter issues, try adding %YAML 1.2 to the top of your file.

Q: Can I use comments in YAML?

A: Yes! This is one of YAML's big advantages over JSON. Use the # symbol for comments.

Q: How do I escape a single quote inside a single-quoted string?

A: In YAML, you escape a single quote by doubling it: 'It''s a beautiful day'.

6. Quick Check Tool

Having trouble finding that invisible tab or bad space? Use our YAML Validator & Formatter (supports YAML-to-JSON and validation). It can:

  • Highlight syntax errors with line numbers.
  • Convert tabs to spaces automatically.
  • Prettify messy YAML for better readability.

Related Errors

Back to Blog