YAML — duplicate key error during parse

YAML parser throws a duplicate key error because the same key appears twice in the same mapping, which is invalid YAML and often a merge conflict artifact.

beginnerdebuggingyamlparsing

Symptoms

error: Mapping keys are not unique
YAML parse fails with "duplicated mapping key"
The file has unresolved git merge conflict markers

Possible causes

A git merge left duplicate keys with conflict markers
A key was copy-pasted and the original was not removed
A YAML anchor merge created an unexpected duplicate

Diagnosis steps

Find duplicate keys

grep -n "^  [a-z_]*:" config.yaml | sort -t: -k2 | uniq -d

Interpretation

Lines with the same key name indicate duplicates.

Check for merge conflict markers

grep -n "<<<<<<<|>>>>>>>" config.yaml

Interpretation

Unresolved conflicts create duplicate keys.

Root cause

The YAML file contains the same key twice in the same mapping, which the parser rejects because YAML mappings must have unique keys.

Fix

Remove the duplicate key, resolve any merge conflicts, and ensure each key appears only once per mapping level.

Verify the fix

Parse the YAML file and confirm no errors; verify the parsed object has the expected structure.

Symptom walkthrough

YAML parser throws a duplicate key error because the same key appears twice in the same mapping, which is invalid YAML and often a merge conflict artifact. The error appears in production but may not surface in local development because the conditions that trigger it depend on the deployment environment or runtime configuration. Understanding the full symptom set helps distinguish this issue from similar errors.

Diagnosis in practice

Follow the diagnosis steps in the frontmatter to isolate the cause. Each step includes a command and an interpretation of the output. The goal is to narrow down whether the issue is in the configuration, the runtime, or the application code. Reproduce the error in a minimal setup before applying a fix.

Root cause

The YAML file contains the same key twice in the same mapping, which the parser rejects because YAML mappings must have unique keys.

Fix

Remove the duplicate key, resolve any merge conflicts, and ensure each key appears only once per mapping level. After applying the fix, monitor the system to confirm the error does not recur under load or in different environments.

Verification

Parse the YAML file and confirm no errors; verify the parsed object has the expected structure. If the verification passes, the fix is confirmed; if not, re-examine the diagnosis steps for missed contributing factors.

Diagnostic commands

Run these commands to reproduce and diagnose the issue:

grep -n "^  [a-z_]*:" config.yaml | sort -t: -k2 | uniq -d
grep -n "<<<<<<<|>>>>>>>" config.yaml