How to Fix Invalid YAML: Indentation, Tabs, Quotes, and Syntax Errors

YAML is designed to be readable, but that readability depends heavily on indentation.

Duck Cloud's YAML Validator checks YAML syntax and structure locally in your browser.

Start with indentation

server:
  host: example.com
   port: 443

The port line has inconsistent indentation.

YAML uses indentation to represent hierarchy, so spacing is part of the syntax.

Avoid tabs

Use spaces for YAML indentation. If a file looks aligned but parsing fails, hidden tab characters are worth checking.

Mappings

A mapping commonly looks like:

database:
  host: localhost
  port: 5432

A missing colon or misaligned child can make the document invalid.

Lists

services:
  - name: api
    port: 3000
  - name: worker
    port: 3001

Nested values under a list item must remain aligned.

Quotes

Strings containing punctuation or values that may be interpreted unexpectedly can be clearer when quoted:

message: "value: with a colon"
version: "1.0"

Duplicate keys

Duplicate mapping keys may be rejected or handled differently by parsers. Treat them as errors unless the consuming specification explicitly defines behavior.

Validate before converting

If you need JSON, first validate YAML, then use YAML to JSON.

If you generate YAML from JSON, use JSON to YAML and validate the result in the target system.

Syntax vs platform schema

A Kubernetes or CI file can be valid YAML and still be invalid for the platform because of an unsupported field, wrong type, or bad API version.

Separate YAML syntax validation from platform schema validation.

Minimal debugging workflow

1. Preserve the original.
2. Validate it.
3. Inspect the reported line and the previous line.
4. Check tabs and indentation.
5. Reduce the file to a minimal failing section.
6. Restore sections gradually.
7. Validate with the target platform.

YAML is easiest to debug when whitespace is treated as syntax rather than decoration.