You are currently viewing Catching YAML Indent Errors Before Deploy

Catching YAML Indent Errors Before Deploy

TL;DR / Summary: Most YAML deploy failures are indentation mistakes that look valid until the parser nests a key under the wrong parent. Validate structure before you push, compare against a known-good file, and never mix tabs with spaces in the same document.

Why YAML fails quietly

YAML uses indentation for hierarchy. A key that slides two spaces left or right can still parse—and attach to the wrong parent. The deploy then reads a missing value as null or inherits a sibling’s settings.

JSON would often throw a syntax error at the same mistake. YAML’s flexibility is the trap: many wrong trees are still well-formed documents.

That is why “it parsed” is not the same as “it is correct.” You need a structural check against the shape you intended.

Establish a single indentation rule

Pick two spaces or four spaces and stick to it for the whole repository. Mixing styles inside one file creates invisible drift when editors auto-indent.

Ban tabs. Some editors display a tab as two spaces and others as four; the file on disk still contains a tab character. Parsers disagree about how far that tab advances.

Editor settings that prevent half the bugs

  • show whitespace characters so spaces and tabs are visible
  • enable “indent using spaces” project-wide
  • add a .editorconfig entry for *.yml and *.yaml

If one teammate uses tabs and another uses spaces, every merge conflict becomes a nesting lottery.

Validate before the pipeline does

Run a local parse step that loads the file and prints the nested structure, not only “OK.” Seeing the tree reveals when env landed under services instead of under the service name.

Compare the parsed tree to a golden example from a successful deploy. Diffing raw text misses reorderings that YAML considers equivalent; diffing the loaded structure catches misplaced keys.

Online converters and formatters help when you need a second opinion. Tools such as those on Masters Tool are useful for a quick structure check before you commit—especially when the CI lint only runs after push.

Common nesting mistakes in real configs

Helm values, Docker Compose, Ansible playbooks, and Kubernetes manifests all suffer the same class of error: a list item’s children indented one level too shallow, so they become siblings of the list instead of children of the item.

Another frequent case: a comment that looks aligned in the editor but sits on a line that still carries leading spaces from a previous key. Delete the line and retype it rather than nudging spaces by eye.

If a key appears twice at different depths, trust the parser’s tree—not your eyes.

Multi-line strings (| and >) have their own indentation rules. Content must sit deeper than the key. Pulling a line left can terminate the block early and turn the rest into new keys.

Anchors and aliases amplify mistakes

YAML anchors reuse a block. If the anchored block was indented wrong, every alias spreads the error. Fix the source block first; re-checking each alias alone wastes time.

Prefer short anchors. Giant reused maps make it hard to see which keys are local overrides and which are inherited.

When in doubt, expand aliases into plain maps for the file you are editing, deploy, then reintroduce anchors carefully. Clarity beats cleverness on deploy day.

Boolean and unquoted string traps

Unquoted yes, no, on, and off may become booleans depending on the YAML version and library. Country codes, feature flags, and version labels are frequent victims.

Quote values that must stay strings. The indentation can be perfect and the type still wrong.

Numbers that are not numbers

  • version strings like 1.10 that become floats
  • leading-zero IDs that become octal in older parsers
  • large integers that lose precision in some languages

Quoting is cheaper than debugging a typed value that “looked fine” in the file.

A pre-deploy checklist that fits in five minutes

Open the changed YAML. Confirm spaces-only indentation. Parse locally and print the subtree you edited. Compare against the previous release’s parsed tree for that section. Quote any ambiguous scalars.

If the change touches secrets or image tags, verify those leaves sit under the expected service key—not under a neighbour that happened to share a similar name.

Parse, print, compare. Do not rely on “it looks indented.”

Keep a tiny sample file in the repo that intentionally shows correct nesting for newcomers. Documentation that only says “use two spaces” is not enough.

When the pipeline still rejects the file

Read the line number in the error, then inspect the parent keys above it. The reported line is often where the parser noticed a problem, not where the indent first went wrong.

Walk upward until the nesting matches your mental model again. Fix at the first wrong level; lower lines often realign once the parent is corrected.

After a fix, re-run the same local parse you used before push. Matching CI is the goal—catching the issue twice in CI is not a badge of thoroughness. The habit that matters is seeing the tree before the remote runner does.

Tabs that sneak in from editors

Some editors insert tabs when you press Tab even if the project wants spaces. Convert the file explicitly before commit, and turn on “render whitespace” for YAML paths so tabs cannot hide beside similar-looking spaces.

A single tab under a list item can shift an entire subtree without looking broken in a narrow diff view. Expand the diff and inspect the gutter marks before you merge.