Provided list of item keys contains duplicates (BatchWriteItem)

In breve — La tua richiesta BatchWriteItem contiene due o più operazioni sulla stessa chiave primaria (due put di una chiave, o un put e un delete di essa). Un singolo batch non può agire su un Item più di una volta, quindi DynamoDB rifiuta l'intero batch. Collassa i duplicati a un'operazione per chiave prima di inviare.

Cosa significa

ValidationException: Provided list of item keys contains duplicates

BatchWriteItem esegue fino a 25 operazioni put/delete. Ogni operazione nella richiesta deve puntare a una chiave primaria distinta. Se due voci PutRequest/DeleteRequest si risolvono nella stessa chiave (partition key, o partition + sort key), DynamoDB fa fallire l'intera chiamata con questa ValidationException HTTP 400 — non viene scritto nulla. Non è ripetibile senza modifiche.

Perché succede

Lo stesso Item messo (put) due volte in un batch — comunemente quando una lista di origine ha record duplicati e mappi ciascuno a un PutRequest.
Un put e un delete della stessa chiave nello stesso batch — sono comunque due operazioni su un Item, comunque rifiutate.
Costruzione di batch senza deduplicazione su un flusso di eventi che ripete una chiave.
Svista sulla chiave composita — due righe che pensavi distinte condividono partition + sort key.
Job ETL / bulk-load (Glue, importer personalizzati) che non uniscono per chiave prima di suddividere.

Come risolverlo

Collassa a un'operazione per chiave, mantenendo la logica ultima scrittura vince:

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

Usa overwrite_by_pkeys di boto3 se usi il batch_writer di Python — batch_writer(overwrite_by_pkeys=['pk', 'sk']) scarta una richiesta in buffer quando un Item appena aggiunto ha la stessa chiave primaria, così l'ultima scrittura per ogni chiave vince.
Suddividi in 25 operazioni per BatchWriteItem dopo la deduplicazione, e riprova gli UnprocessedItems (throttling — un aspetto separato).
Devi scrivere e poi eliminare la stessa chiave? Suddividili in richieste separate, oppure usa TransactWriteItems (che anch'esso vieta due azioni su un Item, ma rende l'intento esplicito).

Stai ispezionando un bulk load prima di eseguirlo? L'app desktop DynoTable mostra gli Item per chiave così le chiavi duplicate messe in coda per lo stesso batch risaltano.

Riproducilo

Un BatchWriteItem che contiene due volte la stessa chiave primaria:

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

Output reale:

ValidationException: Provided list of item keys contains duplicates
HTTP 400

L'intero batch viene rifiutato — nessuna delle due scritture va a buon fine. Poiché un batch non ha alcuna garanzia di ordinamento, DynamoDB non decide quale dei due duplicati debba vincere, quindi deduplica per chiave prima di costruire la richiesta.

Errori correlati

Provided list of item keys contains duplicates (BatchGetItem) — la stessa regola sul percorso di lettura.
ConditionalCheckFailedException — un guard per-Item fallito al momento della scrittura.
Esempio di codice: BatchWriteItem in Node.js — una scrittura batch suddivisa corretta da adattare.
Impara: Batch operations

Riferimenti

Ultima verifica 2026-07-13 rispetto alla documentazione ufficiale AWS collegata sopra.

Riprodotto il 2026-07-26 su DynamoDB Local 2.x con AWS SDK for JavaScript v3.1095.0 — l'output qui sopra è riportato alla lettera.