YAML indentation errors: find the line that breaks your CI deploy

PublishedToolYAML Validator & Formatter

Contents
  1. Why CI deploys fail
  2. How to check: finding the line that's wrong
  3. Common sticking points
  4. Wrapping up
  5. Frequently asked questions

You've probably tweaked a GitHub Actions or GitLab CI config file, committed it, and then got a message saying the deploy failed. You stare at the diff and not a single command has changed — but the actual cause is often a single space you can't see. YAML uses indentation levels instead of braces to define hierarchy, so whitespace is literally part of the syntax.

Summary ① YAML uses line breaks and indentation levels, not braces or commas, to show hierarchy ② Items at the same level must have exactly the same number of indent spaces — if one is off, it gets read as a different level or the structure breaks entirely ③ Even if things look aligned on screen, only a parser can tell you the real space count or whether tabs are mixed in

Why CI deploys fail

Most CI/CD config files — GitHub Actions, GitLab CI, Kubernetes manifests, docker-compose — are written in YAML. Unlike JSON, YAML doesn't mark the start and end of child items with braces or brackets. It shows hierarchy purely through how many spaces a line is indented.

Lines with the same indent level belong to the same level, and a more deeply indented line becomes a child of the line right above it. Because of this rule, the number of spaces is part of the syntax, and a single space difference gets read as a completely different structure.

The problem is that this difference is hard to see. In your editor, three spaces or four looks about the same, and lines you copy from another document or someone else's code bring the original indentation with them, so they easily fall out of step with the lines around them.

For example, if one item in a multi-step steps list is missing a single space, that item shifts to the wrong level, or the parser can't make sense of the structure at all and throws an error. CI logs often only show a short failure message, so it's hard to tell from the log alone which line is the culprit.

How to check: finding the line that's wrong

Turn on your editor's "show invisible characters" setting and spaces and tabs appear as different symbols, so you can tell apart characters that look identical on screen. "Indent guides" also help — you can see at a glance whether lines at the same level line up on the same vertical line.

If that still doesn't find it, you can count from the top of the file line by line. Matching the child indentation against the parent line by hand will eventually reveal the mismatch, but it takes longer as the file grows, and it's easy to miscount along the way.

Check it with our tool. Paste in your YAML or load the file, and the built-in parser re-reads the structure and tells you the line number where the indentation is off.

YAML Validator & Formatter

Free · No sign-up · See the YAML error line number right in your browser

Common sticking points

SituationCause
The editor shows everything aligned but you still get an errorTabs and spaces are mixed, so it looks the same on screen but the parser treats them as different indentation
You pasted a YAML snippet from another document and got an errorThe original indentation doesn't match the current file, so the levels fall out of step with the surrounding lines
Only one item in a list (items starting with -) errorsIf sibling items differ by even one space, that item gets separated into a different level
The CI log doesn't show an error line numberThe log only tells you parsing failed — to find the offending line, you have to validate the file yourself

Every situation in the table comes from the same rule: indentation level determines hierarchy. Run the file through a validator and you can see these differences, which are easy to miss, pinpointed by line number.

Wrapping up

CI/CD config files are mostly YAML, and YAML shows hierarchy through indentation levels instead of braces. Items at the same level need exactly the same number of spaces, and a single space off means they're read as a different level — or parsing fails outright.

You can check by eye with your editor's show-whitespace setting, or count the spaces yourself, but the longer the file, the faster and more accurate it is to drop it into a validator and get the line number straight away.

YAML Validator & Formatter

Free · No sign-up · See the YAML error line number right in your browser

Frequently asked questions

The CI log doesn't show an error line number. How do I find it?

The CI tool's own log usually just says parsing failed, and often won't give you the exact line. Paste the config file as-is into a separate YAML validator, and the parser will tell you the line number where the hierarchy first went wrong.

Should I use 2 spaces or 4 spaces for indentation?

The YAML spec itself doesn't mandate a number. What matters is that within one file, items at the same level must use the same number of spaces — so pick 2 or 4 and stay consistent across the whole project. The GitHub Actions and GitLab CI example docs generally use 2 spaces.

Can I mix tabs and spaces?

No. The YAML spec doesn't allow tab characters for indentation. Every editor renders a tab as a different width, so the parser has no consistent way to know whether one tab equals two spaces or four.

This article was adapted from our Korean original. Read the Korean original

Related articles

  1. YouTube Auto-Generated Captions vs Manual Subtitles: SRT or VTT?YouTube's auto-generated captions misspell names and technical terms. Here's why manual subtitles are more accurate, and when to save SRT, VTT, or TXT.
  2. Add Line Numbers to Text: 5 Formats and Zero PaddingNumber every line of your text or code as 1., [1], 01., or (1) — plus how zero-padding width is calculated and how to skip blank lines.
  3. Anagram Checker: How to Tell If Two Phrases Are AnagramsLearn a 4-step manual way to check whether two words or phrases are anagrams, plus the hashing algorithm that makes the check instant.
  4. Profanity Filter Guide: Match Rules and Avoiding False PositivesLearn how profanity filters match words, why partial matching over-censors, and how to mask swear words without flagging normal text.
  5. Base32 Encoding Explained: 5-Bit Conversion, Padding, OTP KeysHow Base32 turns bytes into 5-bit chunks, why 0, 1, 8 and 9 never appear, how = padding works, and how to decode a Google Authenticator secret key.
  6. Base64 Encoding and Decoding: 6-Bit Mapping and Padding RulesSee how Base64 turns 8-bit data into 6-bit characters, why it adds 33% size, how = padding works, and why UTF-8 keeps Hangul and emoji intact.

Related tools