{"id":117,"date":"2026-11-17T09:20:00","date_gmt":"2026-11-17T09:20:00","guid":{"rendered":"https:\/\/www.masters-tool.com\/blog\/?p=117"},"modified":"2026-11-11T03:39:06","modified_gmt":"2026-11-11T03:39:06","slug":"yaml-indent-errors-before-deploy","status":"publish","type":"post","link":"https:\/\/www.masters-tool.com\/blog\/yaml-indent-errors-before-deploy\/","title":{"rendered":"Catching YAML Indent Errors Before Deploy"},"content":{"rendered":"<p><strong>TL;DR \/ Summary:<\/strong> 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.<\/p>\n<h2>Why YAML fails quietly<\/h2>\n<p>YAML uses indentation for hierarchy. A key that slides two spaces left or right can still parse\u2014and attach to the wrong parent. The deploy then reads a missing value as null or inherits a sibling\u2019s settings.<\/p>\n<p>JSON would often throw a syntax error at the same mistake. YAML\u2019s flexibility is the trap: many wrong trees are still well-formed documents.<\/p>\n<p>That is why \u201cit parsed\u201d is not the same as \u201cit is correct.\u201d You need a structural check against the shape you intended.<\/p>\n<h2>Establish a single indentation rule<\/h2>\n<p>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.<\/p>\n<p>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.<\/p>\n<h3>Editor settings that prevent half the bugs<\/h3>\n<ul>\n<li>show whitespace characters so spaces and tabs are visible<\/li>\n<li>enable \u201cindent using spaces\u201d project-wide<\/li>\n<li>add a .editorconfig entry for <code>*.yml<\/code> and <code>*.yaml<\/code><\/li>\n<\/ul>\n<p>If one teammate uses tabs and another uses spaces, every merge conflict becomes a nesting lottery.<\/p>\n<h2>Validate before the pipeline does<\/h2>\n<p>Run a local parse step that loads the file and prints the nested structure, not only \u201cOK.\u201d Seeing the tree reveals when <code>env<\/code> landed under <code>services<\/code> instead of under the service name.<\/p>\n<p>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.<\/p>\n<p>Online converters and formatters help when you need a second opinion. Tools such as those on <a href=\"https:\/\/www.masters-tool.com\/\">Masters Tool<\/a> are useful for a quick structure check before you commit\u2014especially when the CI lint only runs after push.<\/p>\n<h2>Common nesting mistakes in real configs<\/h2>\n<p>Helm values, Docker Compose, Ansible playbooks, and Kubernetes manifests all suffer the same class of error: a list item\u2019s children indented one level too shallow, so they become siblings of the list instead of children of the item.<\/p>\n<p>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.<\/p>\n<blockquote><p>If a key appears twice at different depths, trust the parser\u2019s tree\u2014not your eyes.<\/p><\/blockquote>\n<p>Multi-line strings (<code>|<\/code> and <code>&gt;<\/code>) 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.<\/p>\n<h2>Anchors and aliases amplify mistakes<\/h2>\n<p>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.<\/p>\n<p>Prefer short anchors. Giant reused maps make it hard to see which keys are local overrides and which are inherited.<\/p>\n<p>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.<\/p>\n<h2>Boolean and unquoted string traps<\/h2>\n<p>Unquoted <code>yes<\/code>, <code>no<\/code>, <code>on<\/code>, and <code>off<\/code> may become booleans depending on the YAML version and library. Country codes, feature flags, and version labels are frequent victims.<\/p>\n<p>Quote values that must stay strings. The indentation can be perfect and the type still wrong.<\/p>\n<h3>Numbers that are not numbers<\/h3>\n<ul>\n<li>version strings like <code>1.10<\/code> that become floats<\/li>\n<li>leading-zero IDs that become octal in older parsers<\/li>\n<li>large integers that lose precision in some languages<\/li>\n<\/ul>\n<p>Quoting is cheaper than debugging a typed value that \u201clooked fine\u201d in the file.<\/p>\n<h2>A pre-deploy checklist that fits in five minutes<\/h2>\n<p>Open the changed YAML. Confirm spaces-only indentation. Parse locally and print the subtree you edited. Compare against the previous release\u2019s parsed tree for that section. Quote any ambiguous scalars.<\/p>\n<p>If the change touches secrets or image tags, verify those leaves sit under the expected service key\u2014not under a neighbour that happened to share a similar name.<\/p>\n<blockquote><p>Parse, print, compare. Do not rely on \u201cit looks indented.\u201d<\/p><\/blockquote>\n<p>Keep a tiny sample file in the repo that intentionally shows correct nesting for newcomers. Documentation that only says \u201cuse two spaces\u201d is not enough.<\/p>\n<h2>When the pipeline still rejects the file<\/h2>\n<p>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.<\/p>\n<p>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.<\/p>\n<p>After a fix, re-run the same local parse you used before push. Matching CI is the goal\u2014catching the issue twice in CI is not a badge of thoroughness. The habit that matters is seeing the tree before the remote runner does.<\/p>\n<h2>Tabs that sneak in from editors<\/h2>\n<p>Some editors insert tabs when you press Tab even if the project wants spaces. Convert the file explicitly before commit, and turn on \u201crender whitespace\u201d for YAML paths so tabs cannot hide beside similar-looking spaces.<\/p>\n<p>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.<\/p>\n","protected":false},"excerpt":{"rendered":"<p>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 [&hellip;]<\/p>\n","protected":false},"author":1,"featured_media":42,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[2],"tags":[],"class_list":["post-117","post","type-post","status-publish","format-standard","has-post-thumbnail","hentry","category-tool-tutorials","entry","has-media"],"_links":{"self":[{"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/posts\/117","targetHints":{"allow":["GET"]}}],"collection":[{"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/users\/1"}],"replies":[{"embeddable":true,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/comments?post=117"}],"version-history":[{"count":1,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/posts\/117\/revisions"}],"predecessor-version":[{"id":118,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/posts\/117\/revisions\/118"}],"wp:featuredmedia":[{"embeddable":true,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/media\/42"}],"wp:attachment":[{"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/media?parent=117"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/categories?post=117"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/www.masters-tool.com\/blog\/wp-json\/wp\/v2\/tags?post=117"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}