Fixing "Encountered two children with the same key" in React

"Encountered two children with the same key" means React's reconciliation algorithm found two or more elements in a rendered list sharing an identical key prop — React relies on keys being unique among siblings specifically to correctly track which DOM elements correspond to which data across re-renders, and a duplicate breaks that guarantee.

This warning means the key prop you're providing for elements in a mapped list isn't actually unique across all siblings in that list — commonly from using an unstable or non-unique field as the key, using an array index in a way that produces collisions after filtering/sorting, or rendering the same underlying data twice within the same list.

Why This Error Happens

React uses key to match elements between renders — determining which existing DOM node corresponds to which piece of data, so it can update, move, or remove exactly the right elements rather than re-rendering the entire list from scratch. When two siblings share a key, React can't reliably distinguish them, leading to genuinely incorrect behavior: state associated with the wrong element, incorrect elements being removed/updated, or visually wrong list ordering after updates.

Reproducing the Error

Using a non-unique field as the key:

function ProductList({ products }: { products: Product[] }) {
  return (
    <ul>
      {products.map((product) => (
        <li key={product.category}>{product.name}</li>
        // Warning if multiple products share the same category —
        // category isn't unique per item, only per group
      ))}
    </ul>
  );
}

Rendering the same data twice within one list, e.g. after a faulty deduplication or merge:

const combinedItems = [...localItems, ...serverItems];
// If localItems and serverItems can overlap (same id present in both),
// mapping over combinedItems with key={item.id} produces duplicate keys

Core Concepts Behind This Error

A genuinely unique, stable identifier (typically a database ID or similarly unique field) is the correct key choice, not any field that happens to look unique in your current test data but isn't guaranteed to be so across all real data — the fix for most instances of this warning is identifying and using the field that's actually unique.

Array index as a key is technically always unique per render (each index appears once), so index-based keys alone don't directly cause this specific duplicate-key warning — but they cause a different, related class of bugs (incorrect state association after insertion/removal/reordering) and are generally discouraged for dynamic lists for that reason, distinct from this specific warning.

Duplicate data appearing in a single rendered list — the same underlying item represented twice — is a data-layer bug surfacing as a key warning; the actual fix is deduplicating the source data (via a Set, a Map keyed by ID, or fixing the query/merge logic producing the duplication), not just changing how keys are generated.

Combining a stable ID with additional context for composite keys is a valid pattern when a single field genuinely isn't unique alone, such as combining a parent ID with a child index when rendering nested, repeatable sub-items that don't have their own independent unique ID.

Fixing "Encountered Two Children With the Same Key"

Fix 1: Use a genuinely unique field (typically an ID) as the key instead of a non-unique attribute:

<ul>
  {products.map((product) => (
    <li key={product.id}>{product.name}</li> // id is actually unique per product
  ))}
</ul>

Fix 2: Deduplicate the underlying data before rendering when the list itself contains genuine duplicates:

const uniqueItems = Array.from(
  new Map(combinedItems.map((item) => [item.id, item])).values()
);

Fix 3: Construct a composite key when no single field is unique alone, combining fields that together are guaranteed unique:

{orders.map((order) =>
  order.lineItems.map((item, index) => (
    <LineItemRow key={`${order.id}-${item.sku}-${index}`} item={item} />
  ))
)}

Fix 4: If the data source itself is producing duplicates (an API response, a database query), fix the actual data issue at the source rather than only patching the rendering layer, since duplicate data likely causes other problems beyond just this warning.

Is It Ever Acceptable to Just Use the Array Index as the Key to Silence This Warning?

Only genuinely as a last resort, and it doesn't actually address the root problem if the underlying issue is real duplicate data — index-based keys will make the warning disappear (since indices are always unique), but they mask a real data-layer bug rather than fixing it, and they introduce their own separate class of state-association bugs for any list that reorders, filters, or has items inserted/removed. Address the actual uniqueness or duplication issue directly instead.

Preventing This Error in Production

Use stable, genuinely unique identifiers (database IDs, UUIDs) as keys by default for any dynamically rendered list, reserving index-based keys only for lists that are truly static and never reorder, filter, or have items added/removed. Add deduplication logic at the data layer (API response processing, state merging logic) when merging data from multiple sources that could plausibly overlap, catching duplication before it ever reaches the rendering layer.

If you hit this warning, check first whether it reflects genuine duplicate data (a data-layer bug worth fixing at the source) versus simply using a non-unique field as the key (a straightforward key-selection fix) — the two require different remedies.