YAML Validation, Linting, and Troubleshooting

YAML•Permalink

Common syntax errors, duplicate keys, parser checks, and validation workflows for debugging YAML faster.

View

Standard Detailed Compact

Export

Copy the compact sheet, download it, or print it.

Download

`D` dense toggle · `C` copy all

Common YAML errors

Examples that help developers debug broken YAML quickly.

Missing space after colon

Show a syntax issue many parsers reject.

↗#

yamlANYyamlsyntax-errorcolon

yaml

name:John

Most YAML style guides and parsers expect a space after the colon in mappings.

Bad list indentation

Illustrate how list nesting can break parsing.

↗#

yamlANYyamlindentationlisterrors

yaml

users:
- name: Jonathan
 role: admin

List item indentation must be consistent and nested fields aligned correctly.

Duplicate key example

Show why repeated keys are dangerous.

↗#

yamlANYyamlduplicate-keyerrors

yaml

app:
  port: 8080
  port: 9090

Some parsers keep the last value silently, which makes duplicate keys a subtle bug.

Run strict linting on a file

Catch common syntax and style problems in one pass.

↗#

bashANYyamlyamllinttroubleshooting

bash

yamllint config.yaml

A reliable baseline check whenever a YAML file fails in CI or deployment.

Parser and conversion debugging

Commands for isolating where YAML breaks or changes unexpectedly.

Debug with Python safe_load

Confirm whether a parser can load a YAML document.

↗#

bashANYyamlpythonparser

bash

python - <<'PY'
import yaml, sys
with open('broken.yaml') as f:
    print(yaml.safe_load(f))
PY

Useful for quick parser verification and inspecting the loaded structure.

Parse YAML with Ruby

Use Ruby's YAML parser to validate a file.

↗#

bashANYyamlrubyparser

bash

ruby -e 'require "yaml"; p YAML.load_file("config.yaml")'

Helpful in environments where Ruby is already installed.

Round-trip through JSON

Convert YAML to JSON to inspect the normalized data model.

↗#

bashANYyamljsonjqdebugging

bash

yq -o=json '.' config.yaml | jq '.'

This helps you see the actual parsed structure separate from YAML formatting quirks.

Review YAML changes carefully

Use Git diff modes that make structural edits easier to inspect.

↗#

bashANYyamlgitdiff

bash

git diff --word-diff=color config.yaml

Particularly helpful when one-space indentation changes are easy to miss.

More in YAML

YAML Config and API Patterns

Application config, OpenAPI, environment settings, and interoperability patterns for YAML across modern tooling.

YAML with yq: Query, Edit, and Transform

High-value yq commands for reading, updating, filtering, converting, and merging YAML in local scripts and CI pipelines.

YAML for DevOps, Kubernetes, and CI

Kubernetes manifests, GitHub Actions, Helm, Compose, and YAML-powered automation workflows with practical validation commands.

YAML Multi-Document Streams

Document separators, multi-resource YAML files, and commands for splitting, filtering, and validating streamed YAML.

YAML Anchors, Aliases, and Merge Keys

Reusable YAML patterns using anchors and aliases, with merge examples and commands for expanding and validating resolved config.

YAML Indentation and Structure

Indentation patterns, nested lists and maps, and practical commands for catching whitespace and structure mistakes.

Recommended next

No recommendations yet.

Browse all sheets →