YAML errors: indentation, tabs and quoting
Match your error to its message, fix the exact line, and watch out for the silent type changes that don't error but alter what your file means.
Nearly every YAML error comes down to indentation: one space too many or too few, a tab, or a list left open. Paste the file into the YAML formatter and, if it's invalid, the message gives you the line and column. It runs in your browser, so a Docker Compose file, a CI workflow or a Kubernetes manifest never leaves your machine. Exact wording depends on the parser, and here are the messages the tool's parser produces.
The indentation errors, one by one
These messages come from running the tool's parser on broken input:
| Input | Message | What it means |
|---|---|---|
a: 1 followed by b: 2 (two spaces) | bad indentation of a mapping entry (2:4) | Line 2 is indented deeper than its sibling with no parent |
| a line starting with a tab | tab characters must not be used in indentation (2:1) | YAML doesn't allow tabs for indenting |
a: [1, 2 left open, another key below | deficient indentation (2:1) | A list or block was never closed |
a: b: c on one line | bad indentation of a mapping entry (1:5) | Two keys back to back on the same line |
The pair in parentheses is line and column, counting from 1. Other parsers word the same problems differently, including the well-known "mapping values are not allowed here", which usually means two key-value pairs were written where only one fits.
How to fix them
- Turn tabs into spaces. Always indent with spaces, and the same number per level (two is enough).
- Line sibling keys up in the same column. Anything under a key and indented further belongs to it.
- Put a space after the colon:
key: value, notkey:value. - Close inline lists and objects (
[...]and{...}), and check the line before the reported one, because parsing fails where it notices the problem, which isn't always where it began. - If a value contains
:or#, wrap it in quotes.
Most of these are preventable. Set your editor to insert spaces when you press Tab, switch on visible whitespace, and run a validator before you commit a config file. A quick paste into the formatter takes seconds and saves a failed deploy.
An example with a docker-compose file
This file fails because ports has one space too many compared with image:
services:
web:
image: nginx
ports:
- "8080:80"The parser answers bad indentation of a mapping entry (4:11): on line 4 a key has an indentation that doesn't match its sibling. Remove the extra space and ports lines up with image, and the file reads as {"services":{"web":{"image":"nginx","ports":["8080:80"]}}}. Look at the line number and the line before it: the error points to the one that doesn't fit, but the culprit can be its neighbor.
The silent errors: types
Harder to spot are values read as another type without any error. With the tool's parser, which follows YAML 1.2 rules:
country: NOis read as the text "NO". A YAML 1.1 parser, such as PyYAML, reads it asfalse. That's the famous Norway problem: a country code turns into a boolean. The same happens withyes,no,onandoff.version: 1.10is read as the number 1.1, and the trailing zero is gone. For a version, write"1.10"in quotes.date: 2024-01-05stays text in the tool, although other parsers turn it into a date.
When formatting, the tool protects ambiguous values: an unquoted yes comes out as 'yes', so that no parser mistakes it for a boolean. If you'd rather leave them bare, there's a Leave yes/no/on/off unquoted option, off by default.
What you lose when you format
Formatting rebuilds the YAML from the data, and that has a cost: comments disappear. If your file has # explanations, keep a copy of that version or review the output before replacing the original. Quote styles and spacing change when it's rewritten as well. To simply check that a file is valid, run the normal mode and discard the output.
Converting between YAML and JSON
The tool has three modes: format YAML, YAML to JSON and JSON to YAML. It's handy for testing what a program really sees: converting to JSON shows the types as they were interpreted. Options such as line width, indent size in spaces and compact {} flow style let you shape the output. To weigh the formats against each other, see JSON vs YAML vs XML: which format should you use?
Frequently asked questions
What does "bad indentation of a mapping entry" mean?
A line's indentation doesn't fit its context: more spaces than it should have, or a key that belongs to no parent. The tool reports the line and column.
Why doesn't YAML allow tabs?
Structure depends on spaces, and tabs render differently in each editor. The specification requires spaces for indentation.
What is the Norway problem in YAML?
In YAML 1.1, the text NO is read as the boolean false, so the country code becomes another type. YAML 1.2 avoids it, but not every parser follows 1.2. Quote ambiguous values.
Why does my version 1.10 become 1.1?
Unquoted, YAML reads it as a number, and numbers don't keep the trailing zero. Write "1.10" in quotes to keep it as text.
Does formatting YAML keep comments?
No. The tool rebuilds the document from the data, so comments aren't preserved.
Is my config file uploaded to a server?
No. It's processed in your browser.
Validate and format your YAML
Format, convert YAML to JSON and JSON to YAML, with errors shown by line and column. Runs locally, free, no signup.
Open YAML Formatter →Related tools
- YAML Formatter: validate, format and convert between YAML and JSON.
- JSON Formatter: validate JSON with errors by line and column.
- XML Formatter: format and validate XML.
- Text Diff: compare two versions of a config file.
You might also like: best developer tools 2026, XML: structure, validation and common errors and Format SQL, HTML and minified code, step by step.