How to Fix Broken YAML Indentation Errors in CI/CD Pipelines

YAML's biggest usability weakness is exactly the feature that makes it readable: indentation carries real structural meaning, not just visual formatting. In most programming languages, inconsistent indentation is an ugly style issue; in YAML, it silently changes what the document actually means, or breaks parsing outright — which is precisely why CI/CD pipeline files (GitHub Actions workflows, GitLab CI configs, Docker Compose files) fail in confusing ways so often.

The single most common cause is mixing tabs and spaces. YAML technically disallows tab characters for indentation entirely, but many editors insert a tab when you press the Tab key unless specifically configured not to, and a single stray tab character mixed in with space-indented lines produces a parsing error that's genuinely hard to spot by eye, since tabs and spaces can look visually identical depending on your editor's rendering.

Inconsistent indentation width is the second major cause — using two spaces for one section of a file and four spaces for another looks fine to a human skimming it, but YAML determines nesting level from the exact number of leading spaces, so a mismatch changes which parent element a line actually belongs to, sometimes producing valid-but-wrong YAML rather than an outright error, which is worse, because it fails silently rather than loudly.

A related but distinct trap is a list item's indentation relative to its parent key. Whether list items need to align with, or be indented further than, their parent key depends on the specific YAML style being used, and copy-pasting a YAML snippet from one context (a tutorial, a different pipeline) into another can quietly break this relationship if the two sources use slightly different conventions.

To debug a broken pipeline YAML, most CI platforms have a syntax validation step or a 'lint' command you can run locally before pushing, which catches indentation and structural errors much faster than the slow feedback loop of pushing a commit and waiting for the pipeline to fail in the platform's UI. GitHub Actions, GitLab CI, and most others all provide some form of this.

Configuring your editor to render whitespace visibly — showing tabs and spaces as distinct characters — makes mixed-indentation bugs immediately obvious instead of invisible, and most editors also support automatically converting tabs to spaces on save, which eliminates the tab-vs-space class of bug entirely going forward rather than needing to catch it each time.

If you're restructuring a YAML file and want to double-check the nesting is actually what you intend before committing it, converting it to JSON with our YAML to JSON tool makes the actual structure explicit and unambiguous — JSON's braces show nesting directly, which can make a subtle indentation mistake in the original YAML immediately obvious once you see the equivalent JSON shape.