DuplicateItemException: duplicate primary key

TL;DR — INSERT PartiQL adalah create yang ketat: jika item dengan primary key yang sama sudah ada, DynamoDB melempar DuplicateItemException alih-alih menimpanya. Untuk mengubah item yang sudah ada, pakai UPDATE PartiQL; untuk mendapatkan semantik replace-if-exists ala PutItem, panggil PutItem itu sendiri — INSERT PartiQL memang sengaja tidak pernah mengganti.

Apa artinya

DuplicateItemException: There was an attempt to insert an item with the
same primary key as an item that already exists in the DynamoDB table.

Data-plane PartiQL (ExecuteStatement / ExecuteTransaction / BatchExecuteStatement) memetakan INSERT ke create bersyarat — ia berhasil hanya ketika belum ada item dengan primary key tersebut. Itu kebalikan dari default PutItem native, yang diam-diam mengganti item yang sudah ada. Jika Anda datang dari SQL dan berharap INSERT gagal pada key duplikat, inilah persis perilaku itu; jika Anda mengharapkan semantik upsert, error inilah kejutannya.

Mengapa itu terjadi

Itemnya memang sudah ada — sebuah percobaan ulang, replay, atau dua penulis berlomba pada key yang sama dan keduanya menjalankan INSERT.
Anda sebenarnya ingin update, bukan create — memindahkan kode bergaya PutItem ke PartiQL dan menganggap INSERT akan mengganti.
Loop percobaan ulang yang tidak idempoten — percobaan pertama berhasil tetapi responsnya hilang (timeout), dan percobaan ulang menyisipkan key yang sama lagi.
Key sintetis yang tidak unik — partition/sort key yang Anda susun lebih sering bertabrakan daripada yang Anda kira (misalnya timestamp berpresisi detik).

Bagaimana cara memperbaikinya

Memperbarui item yang sudah ada? Pakai UPDATE:

UPDATE "orders" SET status = 'shipped' WHERE pk = 'ORDER#123' AND sk = 'META'

Ingin replace-if-exists (semantik PutItem)? Panggil PutItem — PartiQL tidak punya statement upsert, dan default API native persis seperti penimpaan yang Anda cari:
```
await client.send(new PutItemCommand({TableName: 'orders', Item: item}));
```
Perlakukan sebagai sukses ketika create-nya idempoten — jika percobaan ulang menemui DuplicateItemException untuk item yang sudah ditulis percobaan pertama, menangkap dan mengabaikannya sering kali penanganan yang tepat.
Pertahankan INSERT ketika Anda mengandalkan keunikan — exception ini adalah penjaga create-only Anda, padanan PartiQL dari attribute_not_exists() pada kondisi PutItem.

Mencoba statement pada data nyata adalah cara tercepat mendalami pemisahan INSERT/UPDATE — editor PartiQL DynoTable menjalankan statement terhadap tabel live Anda dengan diagnostik inline dan quick-fix, dan DynamoDB Expression Builder memancarkan request API native yang setara ketika Anda justru butuh semantik PutItem.

Cara mereproduksinya

Sebuah INSERT PartiQL untuk primary key yang sudah ada:

await client.send(
  new PutItemCommand({
    TableName: 'orders',
    Item: {pk: {S: 'ORDER#1'}, sk: {S: 'META'}}
  })
);
await client.send(
  new ExecuteStatementCommand({
    Statement: `INSERT INTO "orders" VALUE {'pk':'ORDER#1','sk':'META'}`
  })
);

Keluaran sebenarnya:

DuplicateItem: Duplicate primary key exists in table
HTTP 400

Perlu diketahui kalau Anda menguji secara lokal: DynamoDB Local memunculkannya sebagai DuplicateItem dengan pesan pendek di atas, sedangkan referensi API layanan mendokumentasikannya sebagai DuplicateItemException dengan kalimat yang lebih panjang. Cocokkan pada HTTP 400 plus operasinya, bukan pada nama atau kata-kata persisnya, kalau tidak handler Anda akan berperilaku berbeda terhadap Local dibanding terhadap tabel sungguhan.

Kesalahan terkait

ConditionalCheckFailedException — kembarannya di API native: penjaga attribute_not_exists() yang gagal pada PutItem.
ValidationException: Unexpected from source — penolakan PartiQL umum lainnya.
Pelajari: Contoh PartiQL · PartiQL vs SQL

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.