Common YAML Errors: Examples and Safe Fixes

Four layers behind a YAML error message

1. Presentation syntax: do indentation, indicators, comments, quoted scalars, block scalars, and document markers match the YAML grammar?
2. Composition: are mapping keys unique under the processor's policy, and does every alias refer to a previously anchored node?
3. Resolution and construction: what types do plain scalars and tags become under the selected YAML schema, and can the runtime construct them safely?
4. Application validation: do the keys, value types, versions, references, and business rules satisfy Kubernetes, Compose, a CI provider, or your own configuration contract?

The YAML 1.2.2 specification describes parsing, composing, and constructing as distinct processes with distinct failure points. A generic YAML Validator can report the first layers. It cannot know every application vocabulary.

Common errors at a glance

1. Indentation spaces and tabs

YAML block structure uses indentation spaces. Tab characters must not be used for indentation. A tab may be permitted in other contexts, including quoted content and some in-line separation, so the precise rule is not “YAML forbids every tab.” The reliable configuration convention is simpler: use spaces for all structural indentation and configure the editor to display invisible characters.

services:
  api:
    image: example/api
   ports:
      - "8080:8080"

services:
  api:
    image: example/api
    ports:
      - "8080:8080"

YAML does not require exactly two spaces; consistent indentation establishes scope. Two spaces are a common style, while four can also be valid. Re-indenting invalid source automatically is unsafe because the desired parent-child relationship is not encoded once the whitespace is wrong.

2. Colons, dashes, and separation

A block mapping entry normally uses a colon followed by separation, as in port: 8080. Without the separating space, port:8080 can be read as a plain scalar rather than the intended key-value pair. A colon can legally occur inside a plain scalar when the following character does not create a mapping separator; URLs such as https://example.test illustrate why every colon cannot be banned.

A block sequence entry uses a dash followed by separation. The dash in - item is an indicator, while the hyphen inside us-east-1 is scalar content. Problems arise when a child mapping is not indented under the sequence item or when a dash is added where the application expected one mapping.

servers:
  - name: primary
    port: 443
  - name: backup
    port: 8443

3. Hash characters and comments

An explicit comment begins with # and must be separated from preceding tokens. A hash inside a plain scalar without separation can remain data, as in color: blue#2, but that spelling is easy to misunderstand. Quote values such as issue identifiers, CSS colors, fragments, and shell snippets whenever human readers or downstream tools could disagree.

retries: 3 # temporary limit

ticket: "#1842"
color: "#0ea5b7"

Comments are presentation details and are not part of YAML's representation graph. A formatter may retain many comments, but a YAML-to-JSON conversion cannot represent them in ordinary JSON. LiveParse reports when conversion drops comments rather than claiming losslessness.

4. Quotes and escape sequences

Single-quoted and double-quoted scalars have different escape rules. In a single-quoted scalar, write a literal apostrophe by doubling it: 'it''s ready'. Backslash does not introduce the YAML double-quoted escape set there. In a double-quoted scalar, backslash sequences such as \n, \t, and Unicode escapes are interpreted, and an unknown escape is an error.

windows_path: 'C:\new\tools'
message: "first line\nsecond line"
apostrophe: 'it''s ready'
boolean_word: "off"

Quotes also control type resolution. Under YAML 1.1, plain off may be false; quoted "off" is a string. Under YAML 1.2 core it is already a string, but quoting communicates portable intent. See YAML 1.1 vs 1.2 for the full comparison.

5. Literal and folded block scalars

A literal block marked with | preserves line breaks. A folded block marked with > folds many line breaks to spaces while preserving boundaries around blank or more-indented lines. Chomping indicators + and - control trailing line breaks. The block's content indentation must be deeper than its parent key.

script: |
  set -eu
  echo "deploy"
description: >-
  This becomes one folded line
  without a final line break.

An under-indented content line can end the scalar early and begin a new token. A formatter cannot safely guess whether that line belonged inside the script, was meant to be a sibling key, or should have used an explicit indentation indicator.

6. Duplicate and unexpectedly equivalent keys

YAML mapping keys are required to be unique in the representation model. Some historical libraries accepted duplicates and kept the first or last value, but that makes configuration behavior parser-dependent and can hide security-sensitive overrides. LiveParse enables the parser's strict duplicate-scalar-key check and reports those duplicates rather than choosing a winner. It does not perform deep equality checks between complex sequence or mapping keys.

Resolution can create non-obvious duplicates. Under YAML 1.1, keys such as yes and true may both resolve to the boolean true. A quoted "1" and numeric 1 remain different YAML scalar types but would collide if both were coerced to the JSON property name "1". The YAML-to-JSON types guide explains why LiveParse rejects post-conversion key collisions.

7. Anchors, aliases, and tags

An alias must refer to an anchor that appeared previously in the same document. Misspelling the name, placing the alias first, or expecting it to cross a document marker produces an unidentified alias. Anchors and aliases represent graph identity, not macro text.

defaults: &defaults
  timeout: 10
worker: *defaults

Tags require constructors that understand their semantics. A generic tool can preserve or diagnose !Duration 5m, but it cannot decide what duration object the application expects. LiveParse stops YAML-to-JSON conversion on !!omap, !!pairs, !!binary, !!set, unresolved tags, and application-specific custom tags. It uses a maximum alias count of 50 per YAML document. Under YAML 1.1, an unquoted << merge-tag key stops conversion because merge expansion is disabled; quoted YAML 1.1 "<<" and literal YAML 1.2 Core << remain ordinary keys. Review anchors, aliases, merge keys, and expansion safety before flattening referenced data.

8. Document markers and multi-document streams

Three dashes, ---, can mark the start of a document; three dots, ..., can mark its end. A stream may contain several documents. Directives such as %YAML 1.1 belong before a document start marker. A stray marker or content after an explicit end can create an unexpected document boundary.

Many configuration applications accept exactly one document even though generic YAML permits a stream. Others, including some Kubernetes workflows, intentionally process several resources. Generic syntax success cannot tell you which policy the target uses. LiveParse's YAML-to-JSON policy maps multiple documents into a top-level JSON array and emits a diagnostic; that is a conversion choice, not a rule imposed by the YAML specification.

9. Valid YAML can still be invalid Kubernetes or Compose

A parser can successfully construct this mapping:

apiVersion: apps/v1
kind: Deployment
metadata:
  name: example
spec:
  replicas: "many"

The YAML layer sees strings and mappings. Kubernetes must decide whether the API version and kind exist, whether replicas has the required integer type, whether required fields are present, and whether admission policies allow the resource. The official Kubernetes object model supplies that separate contract.

The Compose Specification likewise defines meanings and constraints for services, networks, volumes, configs, and secrets. A misspelled field can be perfectly legal YAML. A generic validator does not know the installed Compose implementation, platform capabilities, interpolated environment, referenced files, or runtime state.

10. Why a formatter is not an automatic fixer

Formatting requires a parseable interpretation. When indentation or quote boundaries are broken, several repairs may produce different data. A tool that silently guesses can turn a visible syntax error into a valid but incorrect deployment. LiveParse's YAML Formatter rejects invalid input rather than advertising repair.

For valid YAML, formatting still parses and reserializes. It can change quoting, equivalent numeric spelling, flow versus block collections, scalar style, comments, and whitespace. LiveParse stops formatting before a precision-losing number or timestamp would change value. Review a source diff before replacing a checked-in configuration, and use the YAML Viewer to confirm document structure and resolved types, not just visual indentation.

A precise YAML debugging workflow

1. Preserve the original. Work on a copy and keep line endings and invisible characters available for inspection.
2. Select YAML 1.2 or 1.1 deliberately. Match the real consumer rather than whichever mode produces fewer errors.
3. Fix the earliest bounded diagnostic. One missing quote or indentation error can create many later messages.
4. Inspect resolved nodes. Confirm strings, booleans, numbers, nulls, mappings, sequences, tags, anchors, aliases, and document count.
5. Format only after validation. Diff the reserialized result and retain comments or source conventions that still matter.
6. Run application validation. Use Kubernetes, Compose, CI, or service-specific tooling with the correct version and environment.
7. Test conversion separately. If producing JSON, review warnings and conversion stops for comments, aliases, alias or complex keys, unsupported tags, YAML 1.1 merge keys, multiple documents, unsafe decimals, non-finite values, and timestamp precision; then inspect with the JSON Formatter and Validator.

The same layered principle applies to XML: the XML Validator checks well-formedness without claiming DTD, XSD, or business validity. Naming what a tool proves is more valuable than a broad green “valid” label.