yaml did not find expected key: Fix Mapping and Indentation Failures (2026)

Published February 28, 2026 · 7 min read

Fix It With a Tool

Validate and transform YAML before pushing

Run structure checks and safe format conversion before CI to prevent parser errors from reaching deploy.

Open YAML Validator Open YAML to JSON

Need the canonical expected-key runbook? For error converting YAML to JSON: did not find expected key, use the anchors and merge-key failure checks for CI-vs-Compose branching and line-number triage. Push blocked right after YAML fixes? Use the git push rejected non-fast-forward decision path and inspect exactly what will ship with Git Diff Viewer before retrying branch updates. If parse errors are fixed but nginx now logs upstream timed out, switch to the Docker upstream-timeout matrix.

Most YAML parse failures are small structural mistakes that become expensive only because they are hard to spot in long config files. This guide uses a deterministic triage order so you can isolate the failing block and fix it in minutes.

Table of contents

  1. Identify the exact YAML parser error message
  2. Run a fast triage workflow
  3. Fix patterns with before/after examples
  4. Harden your CI check
  5. Pre-commit checklist

1. Diagnose yaml did not find expected key vs related parser errors

These messages usually point to formatting, not logic:

Warning: Fix one error at a time and re-validate. A single indentation mismatch can cascade into many false follow-up errors.

2. Run a fast triage workflow

  1. Copy the exact failing line range from CI output.
  2. Replace all tabs with spaces in that block.
  3. Align sibling keys to the same indentation depth.
  4. Quote values containing :, #, or leading special characters.
  5. Validate the small block first, then the full document.
# locate tabs quickly
rg -n "\t" your-config.yaml

# visualize indentation width
sed -n 'start,endp' your-config.yaml | sed 's/ /ยท/g'

3. Fix patterns with before/after examples

Error: mapping values are not allowed here

# bad
env:
  API_URL: https://api.example.com:v1

# good
env:
  API_URL: "https://api.example.com:v1"

Error: did not find expected key

# bad
services:
  web:
    image: myapp:latest
     ports:
      - "8080:8080"

# good
services:
  web:
    image: myapp:latest
    ports:
      - "8080:8080"

Error: tab character in indentation

# bad (tab before image)
services:
	web:
    image: myapp:latest

# good
services:
  web:
    image: myapp:latest
Tip: Keep YAML indentation at two spaces per level and enforce it with editor settings plus a lint rule in CI.

4. Harden your CI check

Catch formatting errors before deploy by validating YAML on pull requests:

# example: validate all yaml files in repo
find . -type f \( -name "*.yml" -o -name "*.yaml" \) -print0 \
  | xargs -0 -n1 yamllint

If you need a quick browser-based spot check during debugging, validate suspect blocks first, then re-run your repo-level lint command.

5. Pre-commit checklist

FAQ

Why does my YAML parse locally but fail in CI?

Different linters/parsers can be stricter in CI. Standardize on one linter version and run the same command locally.

Can comments break YAML parsing?

Yes, if a value includes # without quoting, the parser may treat the rest as a comment and break structure.

What is the safest first step when the error line looks wrong?

Start a few lines above the reported line. YAML parser errors often surface after the true root cause.