Provided list of item keys contains duplicates (BatchWriteItem)

TL;DR — Request BatchWriteItem Anda memuat dua operasi atau lebih pada primary key yang sama (dua put untuk satu key, atau put sekaligus delete untuk key itu). Satu batch tidak bisa bertindak pada satu item lebih dari sekali, jadi DynamoDB menolak seluruh batch. Leburkan duplikat menjadi satu operasi per key sebelum mengirim.

Apa artinya

ValidationException: Provided list of item keys contains duplicates

BatchWriteItem menjalankan hingga 25 operasi put/delete. Setiap operasi dalam request harus menyasar primary key yang berbeda. Jika dua entri PutRequest/DeleteRequest mengarah ke key yang sama (partition key, atau partition + sort key), DynamoDB menggagalkan seluruh panggilan dengan ValidationException HTTP 400 ini — tidak ada apa pun yang tertulis. Ia tidak bisa dicoba ulang tanpa diubah.

Mengapa itu terjadi

Item yang sama di-put dua kali dalam satu batch — umumnya ketika daftar sumber memiliki record duplikat dan Anda memetakan masing-masing ke PutRequest.
Put dan delete untuk key yang sama dalam batch yang sama — tetap dua operasi pada satu item, tetap ditolak.
Menyusun batch tanpa deduplikasi dari aliran event yang mengulang sebuah key.
Kelalaian pada composite key — dua baris yang Anda kira berbeda ternyata berbagi partition + sort key.
Job ETL / bulk-load (Glue, importer buatan sendiri) yang tidak menggabungkan berdasarkan key sebelum memotong batch.

Bagaimana cara memperbaikinya

Leburkan menjadi satu operasi per key, dengan aturan penulisan terakhir yang menang:

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

Pakai overwrite_by_pkeys milik boto3 jika Anda memakai batch_writer di Python — batch_writer(overwrite_by_pkeys=['pk', 'sk']) membuang request yang sudah dibuffer ketika item yang baru ditambahkan punya primary key sama, sehingga penulisan terakhir untuk tiap key yang menang.
Potong ke 25 operasi per BatchWriteItem setelah deduplikasi, dan coba ulang UnprocessedItems (throttling — urusan terpisah).
Perlu menulis lalu menghapus key yang sama? Pisahkan ke request yang berbeda, atau pakai TransactWriteItems (yang juga melarang dua aksi pada satu item, tapi membuat maksudnya eksplisit).

Ingin memeriksa bulk load sebelum menjalankannya? Aplikasi desktop DynoTable menampilkan item berdasarkan key sehingga key duplikat yang mengantre di batch yang sama langsung terlihat.

Cara mereproduksinya

Sebuah BatchWriteItem yang memuat primary key sama dua kali:

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

Keluaran sebenarnya:

ValidationException: Provided list of item keys contains duplicates
HTTP 400

Seluruh batch ditolak — tidak satu pun penulisan mendarat. Karena batch tidak menjamin urutan, DynamoDB tidak akan memutuskan duplikat mana dari keduanya yang harus menang, jadi deduplikasi berdasarkan key sebelum menyusun request.

Kesalahan terkait

Provided list of item keys contains duplicates (BatchGetItem) — aturan yang sama di jalur baca.
ConditionalCheckFailedException — penjaga per-item yang gagal saat penulisan.
Contoh kode: BatchWriteItem di Node.js — penulisan batch terpotong yang benar untuk Anda adaptasi.
Pelajari: Operasi batch

Referensi

Terakhir diverifikasi 2026-07-13 terhadap dokumentasi resmi AWS yang ditautkan di atas.

Direproduksi 2026-07-26 terhadap DynamoDB Local 2.x dengan AWS SDK for JavaScript v3.1095.0 — keluaran di atas dikutip apa adanya.