Provided list of item keys contains duplicates (BatchWriteItem)

TL;DR — Deine BatchWriteItem-Anfrage enthält zwei oder mehr Operationen auf demselben Primärschlüssel (zwei Puts eines Keys, oder ein Put und ein Delete davon). Ein einzelner Batch kann auf ein Item nicht mehr als einmal wirken, also weist DynamoDB den gesamten Batch ab. Fasse Duplikate zu einer Operation pro Key zusammen, bevor du sendest.

Was es bedeutet

ValidationException: Provided list of item keys contains duplicates

BatchWriteItem führt bis zu 25 Put-/Delete-Operationen aus. Jede Operation in der Anfrage muss einen distinkten Primärschlüssel anvisieren. Wenn zwei PutRequest-/DeleteRequest-Einträge auf denselben Key auflösen (Partitionsschlüssel, oder Partition + Sort Key), lässt DynamoDB den ganzen Aufruf mit dieser HTTP 400 ValidationException scheitern — nichts wird geschrieben. Es ist unverändert nicht wiederholbar.

Warum es passiert

Dasselbe Item zweimal geput in einem Batch — häufig, wenn eine Quellliste doppelte Datensätze hat und du jeden auf ein PutRequest abbildest.
Ein Put und ein Delete desselben Keys im selben Batch — immer noch zwei Operationen auf einem Item, immer noch abgewiesen.
Batches ohne Deduplizierung bauen über einen Strom von Events, die einen Key wiederholen.
Composite-Key-Versehen — zwei Zeilen, die du für distinkt hieltst, teilen Partition + Sort Key.
ETL-/Bulk-Load-Jobs (Glue, eigene Importer), die nicht nach Key zusammenführen, bevor sie blocken.

So behebst du es

Fasse zu einer Operation pro Key zusammen, wobei der letzte Write gewinnt:

import {marshall} from '@aws-sdk/util-dynamodb';

const byKey = new Map();
for (const item of records) {
  byKey.set(`${item.pk}#${item.sk ?? ''}`, {PutRequest: {Item: marshall(item)}});
}
const batch = [...byKey.values()]; // <= one op per key

Nutze boto3s overwrite_by_pkeys, wenn du den Python-batch_writer verwendest — batch_writer(overwrite_by_pkeys=['pk', 'sk']) verwirft eine gepufferte Anfrage, wenn ein neu hinzugefügtes Item denselben Primärschlüssel hat, sodass der letzte Write für jeden Key gewinnt.
Blocke nach dem Deduplizieren auf 25 Operationen pro BatchWriteItem und wiederhole UnprocessedItems (Throttling — ein separater Belang).
Musst du denselben Key schreiben und dann löschen? Teile sie auf separate Anfragen auf, oder nutze TransactWriteItems (das ebenfalls zwei Aktionen auf einem Item verbietet, aber die Absicht explizit macht).

Einen Bulk-Load prüfen, bevor du ihn ausführst? Die DynoTable-Desktop-App zeigt Items nach Key, sodass doppelte Keys, die für denselben Batch in der Warteschlange stehen, hervorstechen.

So reproduzierst du es

Ein BatchWriteItem, das denselben Primärschlüssel zweimal enthält:

await client.send(
  new BatchWriteItemCommand({
    RequestItems: {
      orders: [
        {PutRequest: {Item: {pk: {S: 'DUP'}, sk: {S: 'META'}}}},
        {PutRequest: {Item: {pk: {S: 'DUP'}, sk: {S: 'META'}}}}
      ]
    }
  })
);

Echte Ausgabe:

ValidationException: Provided list of item keys contains duplicates
HTTP 400

Der gesamte Batch wird abgewiesen — keiner der beiden Writes landet. Da ein Batch keine Reihenfolgegarantie hat, entscheidet DynamoDB nicht, welches der beiden Duplikate gewinnen soll — dedupliziere also nach Key, bevor du die Anfrage baust.

Referenzen

Zuletzt verifiziert am 2026-07-13 gegen die oben verlinkte offizielle AWS-Dokumentation.

Am 2026-07-26 gegen DynamoDB Local 2.x mit dem AWS SDK for JavaScript v3.1095.0 reproduziert — die Ausgabe oben ist wortgetreu.