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

Contents
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.
Free · No sign-up · See the YAML error line number right in your browser

Common sticking points
| Situation | Cause |
|---|---|
| The editor shows everything aligned but you still get an error | Tabs 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 error | The 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 -) errors | If sibling items differ by even one space, that item gets separated into a different level |
| The CI log doesn't show an error line number | The 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.
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