YAML is the config format you meet through CI pipelines, Docker Compose, Kubernetes manifests and GitHub Actions workflows. It is also the format where a single wrong space character silently changes your document's meaning — or where the parser rejects a file that looks perfectly fine. This guide covers the failures that actually happen, what the parser's error messages mean, and where an online YAML formatter fits into the workflow — with the limits stated plainly.

What "formatting" can and cannot do here

An online YAML formatter works in two steps: parse your input into a document tree, then re-emit it with consistent indentation. That has an honest consequence most tool pages don't spell out.

Formatting re-serializes the document. The formatter parses your YAML and writes it back from the parsed model. Two things follow from that. First, inconsistent indentation gets normalized to one consistent width — that's the part you came for. Second, anything the parser discards on the way in is gone on the way out. Comments are the common casualty: a parser keeps the data, not the marginalia, so a formatted file can come back without your # comments.

That's not a bug in any specific tool — it's what parse-and-emit means. The same applies to anchors and aliases in the general case. If your file's comments matter, treat the formatter as a validator first and format a copy, not the original.

Formatting is not validation of anything beyond syntax. A file that parses cleanly is well-formed YAML. Whether it's the YAML you meant — whether timeout: 30 was supposed to be a string or a number, whether that list was supposed to nest under the previous key — is a question no formatter answers. Treat the output as "parses correctly", not "semantically correct".

The tab problem, stated exactly

The most common hard failure is the tab character. YAML forbids tabs in indentation, and the error is unambiguous:

a:
	- x

The parser reports:

Tabs are not allowed as indentation
at line 2, column 1

This message names the line and column, which makes it one of the easier YAML errors to fix. The subtlety is where the tab comes from: copy-pasting config from a terminal or a Slack message is the usual source, because the original file used spaces and the transport introduced tabs. If line 2 never contained a tab in your editor, check what you actually pasted.

"Valid" is not the same as "what you meant"

Here is the part worth internalizing: some inputs that look broken parse without any error at all.

Take key:value — no space after the colon. Several older YAML tools and linters reject this. The parser used by DigDevBox's YAML formatter accepts it — as a single scalar string "key:value", not as a mapping from key to value. No error, no warning. The file is valid YAML; it's just not the structure you intended.

The same class of surprise shows up in list indentation. This parses without complaint:

items:
  - a
   - b

A human reads "b" as a sibling of "a". Depending on the surrounding structure, the parser may read it as a continuation or a nested structure rather than raising an error. The parse succeeds; the meaning shifts.

This is why the honest workflow has three steps, not two: validate (does it parse), inspect (does the re-emitted structure match what you intended — keys, nesting, types), and only then ship. The formatter's output is your inspection artifact: read the re-serialized document, don't just confirm that no error appeared.

A worked example: the inspection catches what the parser doesn't

Here's the case that makes step two non-optional. This input has inconsistent list indentation — the second item is indented one space more than the first:

items:
  - a
   - b

No error. The parse succeeds. But the document you just built is not a list of two items — the deeper-indented line was read as a multi-line plain-scalar continuation, producing the single string "a - b".

You'd never see that from the absence of an error message. You see it the moment you re-emit the parsed document:

items:
  - a - b

One item. The formatter didn't introduce this — your input parsed that way — but its output is the mirror that shows what the parser actually built. That's the inspection step earning its place: validate for hard failures, re-emit to check the shape, and read the shape.

Reading the other common parse errors

Unclosed quotes report precisely:

name: "unclosed

Missing closing "quote
at line 1, column 16

The column points at the end of input, which is where the parser gave up looking — the missing quote is usually earlier in the line.

Mapping values not allowed here appears when a colon follows an unquoted scalar in a context where the parser can't accept a new mapping — typically a colon inside a value like error: failed: connection refused that should have been quoted.

Duplicate keys are the quiet one. Some parsers accept the last occurrence silently, some error. Either way, the intent is ambiguous — if a formatter's output shows a key you expected twice appearing once, an earlier duplicate got merged on input.

Where this leaves you in the workflow

For a CI config or a compose file that fails to load, the practical loop is: paste the file in, fix what the parser names (tabs, unclosed quotes), re-check the re-emitted structure against your intent, and only then commit. The online formatter handles parse-and-reformat in one pass with a configurable indent width, which covers the loop.

What it doesn't do — and no formatter does — is confirm that the document means what you think. That check stays with you, and reading the re-emitted output is the cheapest version of it.