YAML, Indentation, and How Parsers Fail

After reading this you will know why YAML breaks on tabs and misaligned spaces, how to read a parser's line and column error, and how to tell a scalar from a mapping when the whitespace looks the same.

What YAML is and one way it bites you

YAML is a data serialization format built around indentation. Structure comes from how many spaces sit at the start of a line, not from brackets or commas. That makes it pleasant to read and easy to break. A single stray space changes what a value belongs to.

Here is the classic bite. These two documents look almost identical, but they parse to different structures:

Document A, with the list items indented under fruits:

fruits:
  - apple
  - pear

Document B, with the list items at column 0:

fruits:
- apple
- pear

Both are valid YAML and both produce the same result: a key fruits whose value is the list ["apple", "pear"]. YAML allows a sequence under a key to sit at the same indentation as the key. That surprises people who expect indentation to be strict. The real trouble starts when the indentation is inconsistent between sibling items, which is where the linter earns its keep.

When to lint YAML, and when a linter cannot help

Run a linter whenever a YAML file feeds a machine that will reject it at an inconvenient time: a Kubernetes manifest, a GitHub Actions workflow, a Docker Compose file, an Ansible playbook. Those systems parse YAML at deploy time, and their error messages are often worse than the parser's own. Catch the syntax error before the pipeline does.

A linter checks that the text is well formed YAML and reports the first place it fails. It does not check meaning. If your Kubernetes field expects replicas: 3 and you write replicas: three, the YAML is valid: the value is the string "three". The linter is happy. Kubernetes is not. For schema-level checks like that, validate against a schema after the syntax passes.

YAML 1.1 (the version js-yaml follows) treats yes, no, on, and off as booleans. So country: NO becomes country: false. Quote the value as "NO" if you mean Norway. This is a parsing rule, not an error, so no linter will flag it.

The one rule that causes most failures: spaces, never tabs

The YAML specification is explicit. Section 6.1 of the YAML 1.2 spec states: "To maintain portability, tab characters must not be used in indentation." A tab in indentation is a hard error, not a style preference.

The reason is that a tab has no fixed width. Your editor might render it as 4 columns, someone else's as 8. Indentation-based structure cannot survive an ambiguous column count, so the spec bans it outright. Spaces are unambiguous: one space is one column everywhere.

The trap is that a tab and a run of spaces look identical on screen. You cannot see the difference by reading. That is why tab detection is worth a dedicated warning: the character that breaks your file is invisible.

How a YAML parser reports where it failed

A YAML parser reads the text one token at a time and tracks a position as it goes. When it reaches a byte that cannot follow what came before, it stops and reports the position. That position has three parts:

\text{position} = (\text{line}, \text{column}, \text{byte offset})

Here line is counted from 1 (the first line is line 1), column is the character position within that line (js-yaml counts from 0, so the first character is column 0), and the byte offset is the absolute number of characters from the start of the document. All three point at the same spot from different reference frames.

The key thing to understand: the reported line is where the parser noticed the problem, not always where you made it. If you forget to close a quote on line 4, the parser may consume lines 5, 6, and 7 as part of that string and only fail at line 8 when it hits something it cannot fold in. Read upward from the reported line when the error looks nonsensical at that exact spot.

Reproducing the demo: a good document and a broken one

Start from a valid two-document file. YAML separates multiple documents in one file with ---:

---
name: web
replicas: 3
ports:
  - 80
  - 443
---
name: worker
replicas: 1

  1. The linter parses two documents. The first is a mapping with three keys; ports holds the list [80, 443]. The second is a mapping with two keys.
  2. Both are valid, so you see the normalized YAML and the JSON equivalent. The first document becomes {"name":"web","replicas":3,"ports":[80,443]}. Note that 3 and 80 are numbers, not strings, because they are unquoted and look numeric.
  3. Now break it. Replace the two spaces before - 80 with a single tab character. The linter reports a failure near line 5, column 0, with a message about a tab not being allowed in indentation.
  4. Fix the tab, then instead indent - 443 by 4 spaces while - 80 stays at 2. The parser now sees inconsistent sequence indentation and reports the mismatch on the line where the depth changes.

Reading the JSON equivalent to check your intent

The fastest way to confirm that YAML parsed the way you meant is to read its JSON equivalent. JSON has explicit brackets and quotes, so ambiguity disappears. If your YAML says version: 1.0 and the JSON shows "version": 1, you just learned that YAML read 1.0 as the number 1.0 and JSON printed it as 1. Quote it as "1.0" if you needed the string.

This table shows how a few unquoted scalars are typed. The pattern is worth memorizing because these conversions cause real production incidents.

How js-yaml types common unquoted scalars
YAML inputParsed typeJSON output
value: 42number42
value: 3.14number3.14
value: yesbooleantrue
value: nullnullnull
value: 007string"007"
value: "42"string"42"

The 007 row surprises people: a leading zero followed by digits containing an 8 or 9 is not a valid octal number, so it stays a string. Change it to 011 and YAML 1.1 reads it as octal 9. Small differences in the digits change the type.

Indentation depth controls nesting. With list items indented 2 spaces under a key, they become that key's value. Move them to 0 spaces and they stay the key's value (YAML allows this). Give two sibling items different indentation and the parser reports an error at the line where the depth changes.

Common mistakes and how to spot them

Most YAML failures fall into a short list. Learn the shapes and you fix them fast.

Tab in indentation
The invisible killer. If the error is at column 0 or the indentation looks correct, check for a tab. Configure your editor to show whitespace.
Inconsistent depth
Two keys that should be siblings sit at 2 and 3 spaces. The parser sees the deeper one as a child and then fails when the structure does not close cleanly.
Unquoted special character
A value starting with @, &, *, !, %, or containing : (colon then space) needs quoting. time: 10:30 is fine, but note: see item: 4 breaks because YAML reads the second colon as a new mapping.
Missing space after the colon
key:value is a single scalar string, not a mapping. YAML requires key: value with the space.

A colon followed by a space inside a plain scalar is treated as a key separator. Write url: http://example.com and it parses fine because there is no space after that colon, but message: error: failed breaks. Quote any value that contains a colon followed by a space.

Related tools on this site

Once your YAML is valid, you often want to do more with it. Convert it with the JSON ↔ YAML ↔ TOML ↔ XML ↔ CSV converter, or format the JSON equivalent in the JSON Formatter & Validator. To check that valid YAML also matches the shape a service expects, run the resulting JSON through the JSON Schema Validator. If you are comparing two config versions, the JSON Diff shows structural changes. When a quoting problem forces you to escape a string by hand, the String Escaper handles it.

Frequently asked questions

Why does my YAML fail with a tab error when I only pressed space?

Your editor probably converted the space or an autoindent to a tab. Tabs and spaces look identical on screen. Turn on "show whitespace" or "render control characters" in your editor and look at the flagged line. The tab will appear as a distinct glyph or a wider gap.

The error line is blank or way past my actual mistake. Why?

The parser reports where it could no longer continue, not where you slipped. An unterminated quote or a folded block often consumes several lines before the parser gives up. Start at the reported line and read upward until the structure stops making sense.

Is YAML 1.1 or 1.2 being used?

js-yaml, used here, follows YAML 1.2 core schema by default but keeps some 1.1 type behavior, including boolean words like yes and on. If you rely on those being strings, quote them.

Does the linter run my YAML or evaluate custom tags?

No. Parsing uses js-yaml in safe mode, so custom tags and code-execution constructs are rejected rather than run. Everything happens in your browser, so nothing you paste is uploaded.

Can I lint a file with multiple documents?

Yes. Separate documents with --- on its own line. The linter parses each one and reports the first that fails, with the line number counted from the top of the whole file.