Provided list of item keys contains duplicates (BatchWriteItem)

En bref — Ta requête BatchWriteItem contient deux opérations ou plus sur la même clé primaire (deux puts d'une clé, ou un put et un delete de celle-ci). Un seul lot ne peut pas agir sur un élément plus d'une fois, donc DynamoDB rejette le lot entier. Fusionne les doublons en une opération par clé avant d'envoyer.

Ce que ça signifie

ValidationException: Provided list of item keys contains duplicates

BatchWriteItem effectue jusqu'à 25 opérations put/delete. Chaque opération de la requête doit cibler une clé primaire distincte. Si deux entrées PutRequest/DeleteRequest se résolvent en la même clé (clé de partition, ou partition + tri), DynamoDB fait échouer tout l'appel avec ce HTTP 400 ValidationException — rien n'est écrit. Il n'est pas réessayable tel quel.

Pourquoi ça arrive

Le même élément mis deux fois dans un lot — souvent quand une liste source a des enregistrements dupliqués et que tu mappes chacun en PutRequest.
Un put et un delete de la même clé dans le même lot — toujours deux opérations sur un élément, toujours rejeté.
Construire des lots sans dédoublonnage sur un flux d'événements qui répète une clé.
Oubli de clé composite — deux lignes que tu croyais distinctes partagent partition + tri.
Des jobs ETL / de chargement en masse (Glue, importeurs personnalisés) qui ne fusionnent pas par clé avant de découper.

Comment le corriger

Fusionne en une opération par clé, en gardant la dernière écriture :

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

Utilise overwrite_by_pkeys de boto3 si tu utilises le batch_writer Python — batch_writer(overwrite_by_pkeys=['pk', 'sk']) supprime une requête en tampon quand un élément nouvellement ajouté a la même clé primaire, donc la dernière écriture pour chaque clé l'emporte.
Découpe en 25 opérations par BatchWriteItem après dédoublonnage, et réessaie les UnprocessedItems (throttling — une préoccupation distincte).
Besoin d'écrire puis de supprimer la même clé ? Répartis-les sur des requêtes séparées, ou utilise TransactWriteItems (qui interdit aussi deux actions sur un élément, mais rend l'intention explicite).

Tu inspectes un chargement en masse avant de l'exécuter ? L'application de bureau DynoTable montre les éléments par clé, donc les clés dupliquées mises en file pour le même lot ressortent.

Reproduire l'erreur

Un BatchWriteItem contenant deux fois la même clé primaire :

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

Sortie réelle :

ValidationException: Provided list of item keys contains duplicates
HTTP 400

Le lot entier est rejeté — aucune des deux écritures n'aboutit. Comme un lot n'offre aucune garantie d'ordre, DynamoDB refuse de décider lequel des deux doublons devrait l'emporter : dédoublonne par clé avant de construire la requête.

Erreurs liées

Provided list of item keys contains duplicates (BatchGetItem) — la même règle côté lecture.
ConditionalCheckFailedException — un garde par élément qui a échoué au moment de l'écriture.
Exemple de code : BatchWriteItem en Node.js — une écriture de lot découpée correcte à adapter.
Apprends : Batch operations

Références

Dernière vérification le 2026-07-13 par rapport à la documentation officielle AWS liée ci-dessus.

Reproduit le 2026-07-26 sur DynamoDB Local 2.x avec l'AWS SDK for JavaScript v3.1095.0 — la sortie ci-dessus est reproduite telle quelle.