Quick answer
In a mapping, each key should appear only once at the same level.
YAML Duplicate Key
In a mapping, each key should appear only once at the same level. If the same key is repeated, parsers may error or use only the last value.
Common causes
- Copy-pasting blocks and leaving the same key name in multiple places.
- Merging configs that both define the same key.
- Typo intended to be a different key (e.g. env vs envs).
How to fix
- Remove or rename duplicate keys so each key is unique at its level.
- If merging is desired, use a single key and combine values (e.g. arrays) under it.
- Validate with a YAML validator to see which line has the duplicate.
Examples
Bad
name: app name: other
Good
name: app version: other
YAML duplicate key errors happen when the same mapping key appears more than once at the same indentation level. In YAML, keys are meant to be unique within a mapping, so repeated keys can cause parser errors, silent overwrites, or unexpected configuration behavior depending on the parser and its settings. This validator page helps developers, DevOps teams, and platform engineers understand why duplicate keys occur, how different YAML parsers handle them, and how to fix the structure safely. It is especially useful for configuration files, CI/CD pipelines, Kubernetes manifests, application settings, and other machine-readable documents where a small syntax issue can change runtime behavior.
How This Validator Works
This YAML duplicate key checker reviews a mapping for repeated keys at the same level and flags entries that appear more than once. In YAML, a mapping is similar to a key-value object in JSON or a dictionary in many programming languages. When the same key is repeated, some parsers reject the document, while others keep only the last occurrence. The validator helps you identify the conflict before deployment, so you can decide whether to remove the duplicate, rename one of the keys, or merge values into a list or nested structure.
- Detects repeated keys within the same mapping scope
- Highlights where a key appears more than once
- Helps distinguish syntax issues from intended overrides
- Supports safer review of YAML used in automation and infrastructure
Common Validation Errors
Duplicate key issues usually come from copy-paste edits, indentation mistakes, or configuration merges. In YAML, a key may look unique at a glance, but if it appears twice under the same parent object, it is still a duplicate. Some parsers treat this as an error, while others allow it and keep the final value, which can make the problem harder to notice.
- Repeated scalar keys: the same plain key is written twice in one mapping
- Quoted and unquoted duplicates: name and "name" may resolve to the same key depending on parser behavior
- Merge conflicts: combining two YAML fragments can introduce duplicate entries
- Indentation drift: a key may appear duplicated because nested structure was not aligned correctly
- Last-value-wins behavior: some parsers silently keep only the final duplicate value
Where This Validator Is Commonly Used
Duplicate key validation is commonly used anywhere YAML is used as a configuration format. Teams rely on it to catch mistakes before files are committed, deployed, or consumed by automation. It is especially relevant in environments where YAML is parsed by tools that may not behave the same way.
- CI/CD pipeline definitions
- Kubernetes manifests and Helm values files
- Application configuration files
- Infrastructure-as-code workflows
- Build and deployment automation
- Documentation systems that store structured metadata in YAML front matter
Why Validation Matters
Validation matters because YAML is often used to control application behavior, deployment settings, and infrastructure state. A duplicate key can change which value is actually read, or it can cause the entire document to fail parsing. Catching the issue early reduces configuration drift, avoids hard-to-debug runtime behavior, and makes shared files easier to review. For teams working across multiple languages and parsers, validation also helps ensure consistent interpretation of the same document.
Technical Details
YAML mappings are key-value collections, and keys are expected to be unique within a given mapping node. The exact outcome of a duplicate key depends on the parser implementation and configuration. Some parsers enforce uniqueness strictly, while others allow duplicates and resolve them by keeping the last value. This is why a file may appear valid in one environment and fail or behave differently in another.
- YAML mapping: a structured collection of key-value pairs
- Duplicate key: the same key name appears more than once in one mapping
- Parser behavior: may reject duplicates or overwrite earlier values
- Common standards context: YAML 1.1 and YAML 1.2 implementations may differ in edge cases
- Best practice: keep keys unique and use lists or nested objects when multiple values are needed
| Issue | What it means | Typical fix |
|---|---|---|
| Repeated key in one mapping | The same key appears more than once at the same level | Remove the duplicate or rename one entry |
| Accidental overwrite | Later value replaces an earlier one in some parsers | Merge values into a list or nested mapping |
| Merge conflict | Two YAML fragments introduce the same key | Reconcile the source files before combining them |
FAQ
What is a YAML duplicate key?
A YAML duplicate key occurs when the same key name appears more than once within the same mapping level. YAML mappings are intended to have unique keys, so repeating a key can create ambiguity. Depending on the parser, the document may fail validation or the later value may override the earlier one.
Why do duplicate keys cause problems in YAML?
Duplicate keys can cause problems because different parsers handle them differently. Some reject the file, while others silently keep the last value. That inconsistency can lead to configuration drift, unexpected application settings, or deployment issues that are difficult to trace back to the source file.
How do I fix a duplicate key error?
First, locate the repeated key in the same mapping. Then decide whether one value should be removed, renamed, or combined. If you need multiple values, use a list or a nested object instead of repeating the same key. After editing, revalidate the file to confirm the structure is unique and consistent.
Can YAML allow duplicate keys?
Some YAML parsers may allow duplicate keys, but that does not mean it is safe or portable. Even when accepted, the behavior may be to keep only the last value, which can hide mistakes. For reliable configuration, it is best to treat keys as unique and avoid depending on parser-specific duplicate handling.
Is a duplicate key always a syntax error?
Not always. In some environments, duplicate keys are treated as a hard error. In others, the file parses successfully but one value overrides another. Because behavior varies, validation is important even when a file appears to load correctly in one tool or language runtime.
How can I prevent duplicate keys in YAML files?
Use consistent review practices, linting, and validation before merging changes. When editing large configuration files, watch for copy-paste duplication and merge conflicts. It also helps to structure related settings into nested mappings or lists so repeated information is represented explicitly rather than by reusing the same key.
Why does my YAML file work in one tool but fail in another?
Different YAML parsers and libraries do not always enforce the same rules. One tool may reject duplicate keys, while another may accept them and keep the last value. This is why a file can seem valid in one environment and fail elsewhere. Cross-tool validation helps reduce those compatibility issues.
Should I use a list instead of repeated keys?
Yes, if you need to represent multiple values for the same concept, a list is usually the correct YAML structure. Repeating the same key is ambiguous, but a list clearly shows that multiple items belong together. This improves readability and makes the document easier for parsers and humans to understand.
Related Validators & Checkers
- YAML Syntax Validator
- YAML Indentation Checker
- JSON Validator
- XML Validator
- Structured Data Validator
- Configuration File Validator
FAQ
- Can YAML have two keys with the same name?
- No. At the same level, each key must be unique; the second occurrence overwrites or causes an error depending on the parser.
- How do I have multiple values for one key in YAML?
- Use a list as the value: key: [a, b, c] or key: with a newline and list items (e.g. - a, - b).
Fix it now
Try in validator (prefill this example)