Fix YAML "bad indentation of a mapping entry"

What the error means

YAML has no braces. The structure of a document is carried entirely by indentation, so the parser decides which mapping a key belongs to by the column it starts in. bad indentation of a mapping entry means a key starts in a column the parser cannot assign to any open mapping: it is indented more than its siblings but not enough to be a child, or it sits somewhere no mapping exists at all.

In the example, port is indented by five spaces while host and tls use four. Five is not a child of host (that would require host to be a mapping, and it is a plain string), and it is not a sibling either, so the parser stops with this message and a line number.

Why it happens

• One extra or missing space on a single line, usually from a hand edit or a merge conflict resolution. This is by far the most common cause and the hardest to see by eye.
• A tab character used for indentation. YAML forbids tabs for indentation outright; some editors insert them silently when you press Tab. The message is sometimes the more explicit tab characters must not be used in indentation, but older parsers report it as bad indentation.
• Copying from a web page or chat that reflowed the whitespace, so nested blocks lost their alignment.
• A list item and a mapping key mixed at the same level, for example a - name: line followed by a version: line that is not indented under the dash.

How to fix it

1. Paste the document into the validator above. The error card gives the line and column; the column tells you how far off the indentation is.
2. Compare that line with the lines above and below it that belong to the same mapping. All of them must begin in exactly the same column.
3. Replace any tab with spaces. Two spaces per level is the convention, but consistency within a document is what actually matters.
4. Validate again. When the document parses, the validator reports the number of documents and top-level keys, which is a quick sanity check that nothing ended up nested under the wrong parent.

The corrected example:

server:
  host: example.com
  port: 8080
  tls: true

If it still fails

• Kubernetes manifests and CI files often nest lists inside mappings inside lists. Validate the whole file, then paste it into YAML to JSON: the JSON view makes the real nesting obvious in a way indentation never does.
• If the error moves to a different line after each fix, you probably have a block that was pasted with a different indentation width than the rest of the file. Re-indent that block as a unit.
• A document that validates but behaves wrongly usually has a key nested one level too deep rather than a syntax error. Check the JSON view for a key that became a child when it should have been a sibling.