Psych::SyntaxError: did not find expected key while parsing a block mapping: what it means and how to fix it

What the error means

Psych::SyntaxError: did not find expected key while parsing a block mapping means the YAML parser could not interpret your document as valid YAML. In practice, the fastest fix is almost always: correct indentation/tabs and re-validate.

Most common real-world causes

• YAML lost the mapping structure due to indentation or a missing ':'.
• Indentation is inconsistent (YAML uses indentation to define structure).
• Tabs were used for indentation (YAML expects spaces).
• A mapping key is missing a ':' or has no space after ':' (e.g. 'key:value').
• Lists are mis-indented (missing '-' indicator or wrong nesting level).
• Duplicate keys appear in the same mapping (some parsers reject them).
• The file contains invisible/control characters (copy/paste from a non-text source).
• Multi-document YAML streams (---) are handled incorrectly by a tool.

Fix checklist

• Check the previous lines: one bad indentation often triggers this on the next key.
• Start from the reported line/column and fix the FIRST syntax issue you see.
• Replace all tabs with spaces and re-validate.
• Check indentation levels: each nested block should be indented consistently (2 spaces is common).
• Verify mappings: every key ends with ':' and values are correctly indented below.
• Verify lists: items start with '-' and are aligned at the correct indentation level.
• After it validates, convert to JSON and validate strict JSON to spot structural issues.

Code example (ruby)

require 'yaml'

begin
  docs = YAML.safe_load_stream(yaml_text)
  puts "docs=#{docs.length}"
rescue Psych::SyntaxError => e
  puts e.message
end

Validate locally (no upload)

If your YAML contains sensitive data, use local-only tools:

• YAML Validator to validate YAML and see line/column errors.
• YAML ↔ JSON Converter to convert and inspect structure safely.
• JSON Validator to confirm strict JSON after conversion.

Workflow: validate -> fix the first syntax issue -> validate again -> convert if needed.

FAQ

Why does the line number not match what I see? Some tools count lines differently (CRLF vs LF, templates, or multi-doc streams). Fix the first broken line in the raw YAML.

Can YAML be valid but still wrong? Yes. YAML can be syntactically valid but structurally wrong for your app. Convert to JSON and validate the shape.