YAML Validator & Linter (Line Numbers + Type Gotchas)

Paste a broken or suspect YAML file and get every syntax error as line:column with a plain-English fix, lint warnings for duplicate keys and bad indentation, and a list of values that will not load as the type you meant.

Last updatedHow we build & check our tools
Results will appear here once you enter your values.

The five YAML syntax errors behind most failed parses

YAML looks forgiving because it has so little punctuation, and that is exactly why it fails in confusing ways. Whitespace carries the structure, so a mistake you cannot see is still a mistake. These five account for most "my YAML will not parse" reports, and the validator names each one with the line and column where the parser gave up.

  • Tabs for indentation. The YAML 1.2.2 specification (section 6.1) allows only spaces for indentation. A tab pasted from a terminal or an editor set to hard tabs gives errors such as "found character that cannot start any token". The tool lists every tab-indented line, not only the first, with tabs drawn as arrows in the excerpt so you can find them.
  • Inconsistent indentation. Siblings must begin in exactly the same column and children must be deeper than their parent. Mixing two- and four-space steps is legal in places and fatal in others, so the linter also flags a file that nests by different widths even when it parses.
  • Unclosed quotes. A missing closing quote swallows the rest of the file, and the parser only notices at the end. The tool points to the line that opened the quote, not the last line of the file where the parser finally gave up.
  • Missing space after the colon. DEBUG:true is not a key and a value, it is one plain string. Inside a mapping it triggers "can not read a block mapping entry". The fix hint calls this out when it matches the line.
  • Unquoted special characters. A value containing : or #, or starting with @, a backtick, %, * or &, is parsed as syntax rather than text. Wrap the value in quotes.

A parser reports the first structural error and stops, because every later line depends on how that one was read. Fix it, and the tool re-checks as you type. For converting a file that already parses, use the YAML/JSON converter; if the same data is JSON, the JSON validator has the matching rules for that language.

Valid YAML that still loads as the wrong type

A file can pass every syntax check and still mean something you did not intend, because YAML decides the type of an unquoted value by pattern matching, and different loaders use different patterns. YAML 1.1 (2005) and YAML 1.2 (2009) disagree about several of them, and a lot of tooling still follows 1.1. For each risky value the validator shows what a 1.2 loader returns and what a 1.1 loader returns, so you can see whether the two disagree.

  • Yes, no, on, off, y, n. Booleans in 1.1, strings in 1.2. The famous case is the country code NO, which becomes false. Quote it, or write true or false.
  • Versions with a trailing zero. python-version: 3.10 is the float 3.1, and 1.20 is 1.2. Quote versions, image tags and chart versions.
  • Leading zeros. 0755 is octal 493 in YAML 1.1 but decimal 755 in 1.2, and 01234 loses its zero as a zip code. Use the explicit 0o755 form for modes in 1.2, or quote identifiers.
  • Colon-separated digits. 22:22 is the base-60 integer 1342 in 1.1 (22 × 60 + 22), while 8080:80 is safe because 80 is not a valid base-60 digit. This is why Docker Compose documentation tells you to quote port mappings.
  • Timestamps. 2026-10-08 becomes a date object in loaders that support the YAML 1.1 timestamp type (PyYAML, Ruby, js-yaml), and stays a string in loaders limited to the strict 1.2 core schema. If you need the literal text, quote it.
  • Very large integers. Anything above 2^53 − 1 (9,007,199,254,740,991) is rounded by JavaScript-based loaders, so a 19-digit ID such as a snowflake changes its last digits. Quote identifiers.

The Structure summary at the bottom of the results then lists each top-level key with the type it loaded as, which is the fastest way to confirm that replicas is an integer and version is a string.

Lint rules, and why each one matters

Lint rules catch the mistakes that parse successfully but cause trouble later. They are reported with a line and column. Duplicate keys are errors, because the specification forbids them; the rest are warnings and do not stop the file from being valid.

  • Duplicate keys (error). The specification requires unique keys in a mapping, but lenient loaders such as PyYAML keep the last value silently, so an override you added at the bottom of a long Compose or workflow file wins without anyone noticing, and the original is dropped. Strict loaders, including js-yaml and Go yaml.v3, reject the file, and so does this validator. The check is scoped, so the same key in two different list items or two documents is not flagged.
  • Empty values. A key with nothing after it, and no nested block under it, loads as null. That is sometimes intended, but often it is a value that was forgotten or a child block indented to the wrong level. The warning states that the value loads as null.
  • Trailing whitespace. Invisible, noisy in diffs, and part of the string inside a block scalar. Strip it. When a whitespace-only change appears in a review, a diff checker will show which lines it touched.
  • Inconsistent indentation. If most levels nest by two spaces and one nests by six, a later edit is likely to break it. The linter finds the most common step width and flags the lines that differ.
  • Missing space after the colon. key:value is valid, but it is a single string and almost never what was meant.

If you want to compare two versions of a config for drift rather than check one file, the config drift detector is the better fit, and the data format converter handles moving between YAML, JSON and other formats once the file is clean.

A workflow for debugging config files, and the standards behind the checks

When a pipeline or container fails to start and the error message is unhelpful, work through the file in this order.

  1. Paste the file and fix the first syntax error. Tabs and indentation first, then quotes.
  2. Read the type-coercion list. A Compose file with 22:22 or a workflow with python-version: 3.10 is valid and still wrong.
  3. Check the Structure summary: does each top-level key have the type you expect, and is the document count right? A stray --- in the middle of a Kubernetes file turns one document into two.
  4. Clear the duplicate-key errors and empty-value warnings.
  5. Only then validate against the tool's own schema or dry-run, for example the Docker command builder for the flags on the command line, or the Dockerfile generator for the image itself.

Where the rules come from. Syntax errors come from js-yaml, a widely used JavaScript implementation of the YAML 1.2 core schema with the timestamp, merge, binary and set types. The indentation, tab and mapping-key rules follow the YAML 1.2.2 specification at yaml.org/spec/1.2.2. The 1.1 readings shown for booleans, octal numbers and base-60 integers come from the YAML 1.1 type repository at yaml.org/type, which PyYAML and many other loaders still implement. The tool has no schema for your particular application, so it checks that the file is well formed and typed as intended, not that its contents are correct.

Frequently Asked Questions

Common questions about the YAML Validator & Linter (Line Numbers + Type Gotchas)

Nine times out of ten it is whitespace. YAML forbids tab characters for indentation (YAML 1.2 specification, section 6.1), so a single tab pasted from a terminal or an editor set to hard tabs breaks the whole file. Bad indentation means sibling keys do not start in exactly the same column, or a child is not indented deeper than its parent. This tool reports the line and column of the first structural error, lists every tab-indented line, and shows the line with a caret under the problem so you can see it. Replace tabs with spaces (two per level is conventional) and re-run.
From the same team

Turn your GPU into an OpenAI-compatible API endpoint

Wide Area AI routes your LLM API calls to your own hardware over a Cloudflare Tunnel — free local inference with edge caching and automatic cloud failover. Works with any OpenAI SDK.

Start routing — free
VRAM CalculatorCan I Run This AI?AI API Cost CalculatorGPU for Model

Sources & References

YAML Ain't Markup Language version 1.2.2

The current YAML specification.
- Section 3.2.1.1: mapping keys must be unique.
- Section 6.1: tab characters are not allowed in indentation.
- Section 10.3: the core schema (true/false only as booleans, 0o for octal, no timestamp type).
→Source: YAML Language Development Team(2021)

YAML 1.1 language-independent types

The 1.1 type repository still implemented by PyYAML and other loaders.
- bool: y|Y|yes|Yes|YES|n|N|no|No|NO|on|On|ON|off|Off|OFF.
- int: octal 0[0-7_]+ and base-60 [1-9][0-9_]*(:[0-5]?[0-9])+; float requires a decimal point.
- timestamp: ISO 8601 dates such as 2001-12-14.
→Source: yaml.org(2005)

Docker Compose: ports

Compose file reference on short-syntax port mappings.
- Recommends quoting HOST:CONTAINER mappings because YAML 1.1 reads xx:yy with a container port below 60 as a base-60 number.
→Source: Docker Docs(2026)

js-yaml 4 (parser used by this tool)

JavaScript YAML 1.2 parser.
- Default schema adds timestamp, merge, binary, omap, pairs and set to the core schema.
- Errors expose a reason and a 0-based line/column mark, shown here as 1-based line:column.
→Source: nodeca/js-yaml(2026)

Explore More Tools

Explore these related tools for your next step.

developer

Network Latency Calculator

Calculate network latency based on distance and speed.

Try it now
developer

JSON Formatter

Format, validate, and minify JSON with syntax highlighting

Try it now
developer

JSON Validator & Formatter

Validate and format JSON with detailed error messages, tree visualization, and syntax highlighting. Fix JSON errors instantly.

Try it now
developer

CSV JSON Excel Converter

Convert between CSV, JSON, and Excel formats instantly — six conversion modes with browser-based processing

Try it now
developer

Excel to JSON Converter

Convert Excel spreadsheets to JSON with multi-sheet support and custom formatting options

Try it now
developer

YAML to JSON Converter

Convert YAML to JSON or JSON to YAML with full support for comments and anchors

Try it now