Common YAML Mistakes

YAML failures are rarely mysterious once you know the usual suspects.

Tabs vs spaces

Many style guides forbid tabs for indentation. Mixing tabs and spaces looks aligned in some editors but breaks parsers. Configure your editor to insert spaces for YAML.

Off-by-one indent levels

Adding a key one space too far left attaches it to the wrong parent. In Kubernetes, that can move containers out of spec silently in your head—but not to the parser.

Unquoted special scalars

YAML interprets values like yes, no, on, off, and 12345 with typing rules. When you mean a string, quote it:

version: "01.10"
enabled: "yes"

Broken flow collections

Starting [ or { sequences without matching closers produces errors deep in the file. CI generators sometimes emit half-valid flow YAML—validate after paste.

Multiple documents in one paste

Files separated by --- are valid multi-document YAML, but some tools expect a single document. Merging two manifests without understanding document boundaries causes confusing errors.

Double conversion

JSON → YAML → manual edit → JSON can introduce duplicate keys or changed types if intermediate tools reorder or normalize values. Diff after every conversion step.