yaml.composer.ComposerError: found duplicate key: what it means and how to fix it

What the error means

yaml.composer.ComposerError: found duplicate key 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

• The same key appears more than once in the same mapping.
• 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

• Keep only one of the duplicate keys (or merge them) and validate again.
• 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 (python)

# Python (PyYAML) parse + error inspection
import yaml

try:
    docs = list(yaml.safe_load_all(yaml_text))
    print('docs:', len(docs))
except yaml.YAMLError as e:
    print('YAML error:', e)
    # Many errors include line/column info inside the message.

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.