Why YAML breaks so easily
YAML’s structure is carried by indentation, so a single misplaced space can turn a list item into a key or end a mapping early. Unlike JSON, a broken file sometimes still parses, just into a different shape. That makes a validator that understands the spec more useful than eyeballing the file. This page uses the yaml library by Eemeli Aro, which implements both YAML 1.2 and 1.1 and reports problems with their exact position.
The usual culprits are:
- Tabs used for indentation. The spec forbids them outright; many editors insert one without telling you.
- Inconsistent indentation inside a list, where one item is indented by three spaces instead of two.
- An unquoted colon followed by a space inside a value, such as
title: Release notes: v2, which YAML reads as a nested key. - Values starting with a reserved character like
@or a backtick. - Duplicate keys in one mapping. YAML 1.2 says keys must be unique, and this validator treats a repeat as an error.
- Aliases that point to an anchor that does not exist, often after a refactor renamed
&defaults.
Reading the result
Each error comes with a line, a column and, where it helps, a hint such as “Replace the tab with spaces” or “Check for a missing “:” or wrong indentation”. The first problem is highlighted in the input pane, and the output pane keeps showing the last version that parsed, slightly faded, so you can see what the file looked like before the edit that broke it. Multi-document files separated by --- are validated document by document. Use the Tree view on valid input to confirm that a list really is a list and that nested keys sit under the parent you expect.
YAML 1.1 versus 1.2 warnings
The YAML version option chooses which rules apply. In YAML 1.2, no, off, yes and on are ordinary strings. In YAML 1.1, which PyYAML, Ansible and some Kubernetes tooling still follow, they are booleans, so country: NO becomes false. With 1.2 selected you get an informational note on each such value; with 1.1 selected it becomes a warning saying the value will be read as a boolean. Neither stops validation, because both readings are legal YAML; quoting the value removes the ambiguity everywhere.
What a syntax check cannot tell you
A manifest can be flawless YAML and still be rejected by kubectl: a misspelled contianers key or a port written as a string passes this check. The validator knows YAML, not the schema of Kubernetes, GitHub Actions or Compose. For those, convert the file with YAML to JSON and validate it against the published JSON Schema, or run the platform’s own dry run. Nothing you paste is uploaded, so cluster secrets in a manifest stay in your browser.
Examples
Tab character in a Compose file
Invalid: line 3 is indented with a tab, which YAML never allows; replacing it with spaces fixes the file.
services:
web:
image: nginx:1.27
ports:
- "8080:80"
Line 3, column 1: Tabs are not allowed for indentation in YAML
Line 3, column 9: A nested block cannot be used as a key
Line 3, column 9: A key must fit on one lineDuplicate key in a ConfigMap
Invalid: LOG_LEVEL appears twice in the same mapping, and the second occurrence is reported with its line.
apiVersion: v1
kind: ConfigMap
metadata:
name: checkout-config
data:
LOG_LEVEL: info
CACHE_TTL: "300"
LOG_LEVEL: debug
Line 8, column 3: Duplicate key — keys in a mapping must be uniqueMisaligned step in a GitHub Actions job
Invalid: the run key is indented one space less than its sibling name, so it no longer belongs to the list item.
steps:
- name: Install
run: npm ci
- name: Test
run: npm test
Line 5, column 1: Sequence item without - indicatorValid, but ambiguous under YAML 1.1
The file is valid; with YAML 1.1 selected, NO and on are flagged because they will be read as booleans.
shipping:
country: NO
express: on
carrier: "DHL"
shipping:
country: NO
express: on
carrier: "DHL"
Common errors and how to fix them
| Error | Cause | Fix |
|---|---|---|
Tabs are not allowed for indentation in YAMLExplained | A tab character was used to indent a line. | Replace the tab with spaces, and set your editor to insert spaces in YAML files. |
A nested block cannot be used as a keyExplained | An unquoted value contains ": " so it looks like another key, or a line is indented so that it lands inside the wrong block. | Quote the value (“Release notes: v2”) or fix the indentation of the line. |
Duplicate key — keys in a mapping must be uniqueExplained | The same key appears twice at the same level. | Delete or rename one of them; many tools silently keep only the last one. |
Plain value cannot start with reserved character @Explained | A value begins with @ or a backtick, which YAML reserves. | Wrap the value in quotes. |
Sequence item without - indicatorExplained | A line inside a list is indented as if it were a new item but has no leading dash. | Align the line with the other keys of its item, or add the missing "- ". |
Frequently asked questions
Can it validate Kubernetes manifests?
It validates their YAML syntax, including multi-document files separated by —. It does not check Kubernetes field names or types; use kubectl apply --dry-run=server or a schema validator for that.
Why is "no" flagged when my file is valid?
In YAML 1.1 an unquoted no, off, yes or on is a boolean. If any tool in your pipeline reads YAML 1.1, your string may arrive as false. Quote it to be safe.
Does the validator fix indentation automatically?
It points to the exact line and column instead. Indentation is meaning in YAML, so guessing a fix could silently change your data.
Are anchors and aliases supported?
Yes. Anchors (&name) and aliases (*name) are resolved during validation, and an alias that refers to an undefined anchor is reported as an error.