🚨 Ansible Error: 'found a duplicate dict key' — Cause, Fix, and Troubleshooting Guide

Overview

YAML mappings must have unique keys. When the same key appears twice at one level, the second silently overrides the first — so Ansible’s parser raises a warning or error to stop you from losing data:

ERROR! While constructing a mapping from /etc/ansible/site.yml, line 8, column 3, found a duplicate dict key (state). Using last defined value only.

It usually surfaces after a copy-paste that repeats a keyword like state, name, when, or tags.

Symptoms

• A play fails to load (or warns) pointing at a specific duplicated key.
• A parameter you set “does not take effect” because a later duplicate wins.
• The line/column in the message lands on the second occurrence.

ansible-playbook -i inventory.ini site.yml --syntax-check

ERROR! found a duplicate dict key (tags)

Common Root Causes

1. Repeated module parameter

Copy-paste leaves two state: or mode: keys under one module.

2. Repeated task keyword

Two when: or tags: on the same task — only the last applies.

3. Duplicate key in vars/inventory

The same variable defined twice in one vars: block or group_vars file.

4. Merged blocks after refactoring

Combining two tasks and forgetting to delete an overlapping key.

How to diagnose

Let YAML tooling point at the exact line:

yamllint site.yml

site.yml
  9:5   error   duplication of key "tags" in mapping  (key-duplicates)

Or with Python:

python3 - <<'PY'
import yaml
class Strict(yaml.SafeLoader): pass
def no_dup(loader, node, deep=False):
    seen=set()
    for k,_ in node.value:
        key=loader.construct_object(k, deep=deep)
        assert key not in seen, f"duplicate key: {key}"
        seen.add(key)
    return yaml.SafeLoader.construct_mapping(loader, node, deep)
Strict.add_constructor(yaml.resolver.BaseResolver.DEFAULT_MAPPING_TAG, no_dup)
yaml.load(open("site.yml"), Strict)
PY

Fixes

Remove the duplicate parameter

Wrong:

- name: Create dir
  ansible.builtin.file:
    path: /opt/app
    state: directory
    state: present        # duplicate — only this wins

Right:

- name: Create dir
  ansible.builtin.file:
    path: /opt/app
    state: directory

Merge repeated keywords intentionally

Two tags: become one list:

- name: Deploy
  ansible.builtin.copy:
    src: app.conf
    dest: /etc/app.conf
  tags:
    - config
    - deploy

De-duplicate vars

Combine repeated variable definitions into a single key with the intended value.

What to watch out for

• The parser keeps the last value, so a duplicate can mask a bug where the wrong value silently wins — do not just delete one at random, confirm which value is correct.
• Add key-duplicates to your yamllint config and run it in CI to catch this before a run.
• Anchors/aliases and merge keys (<<) can reintroduce a key; check merged content too.

Related

• Ansible Error: ‘Syntax Error while loading YAML’
• Ansible Error: ‘X is not a valid attribute for a Task’
• Taming ansible-lint With AI: From Warnings to Clean Runs