DuplicateItemException: duplicate primary key

TL;DR — Ein PartiQL INSERT ist ein striktes Create: Wenn ein Item mit demselben Primärschlüssel bereits existiert, wirft DynamoDB DuplicateItemException, statt es zu überschreiben. Um das bestehende Item zu ändern, nutze PartiQL UPDATE; um PutItems Replace-if-exists-Semantik zu bekommen, nutze PutItem selbst — PartiQL INSERT ersetzt bewusst nie.

Was es bedeutet

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

Die PartiQL-Data-Plane (ExecuteStatement / ExecuteTransaction / BatchExecuteStatement) bildet INSERT auf ein bedingtes Create ab — es gelingt nur, wenn kein Item mit diesem Primärschlüssel existiert. Das ist der entgegengesetzte Default zum nativen PutItem, das ein bestehendes Item stillschweigend ersetzt. Wenn du von SQL kommst und erwartest, dass INSERT bei einem doppelten Key fehlschlägt, ist das genau dieses Verhalten; wenn du Upsert-Semantik erwartet hast, ist dieser Fehler die Überraschung.

Warum es passiert

• Das Item existiert tatsächlich bereits — ein Retry, ein Replay oder zwei Writer, die auf demselben Key um die Wette laufen und beide INSERT absetzen.
• Du wolltest ein Update, kein Create — PutItem-artigen Code auf PartiQL portiert und angenommen, dass INSERT ersetzt.
• Eine nicht-idempotente Retry-Schleife — der erste Versuch gelang, aber die Antwort ging verloren (Timeout), und der Retry fügt denselben Key erneut ein.
• Ein synthetischer Key, der nicht eindeutig ist — der zusammengesetzte Partition-/Sort-Key kollidiert öfter, als du denkst (z. B. ein Zeitstempel mit Sekundengenauigkeit).

So behebst du es

1. Ein bestehendes Item aktualisieren? Nutze UPDATE:

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

2. Replace-if-exists gewünscht (PutItem-Semantik)? Rufe PutItem auf — PartiQL hat kein Upsert-Statement, und der Default der nativen API ist genau das Überschreiben, das du willst:

   await client.send(new PutItemCommand({TableName: 'orders', Item: item}));

3. Behandle es als Erfolg, wenn das Create idempotent ist — wenn ein Retry auf DuplicateItemException für ein Item trifft, das dein erster Versuch bereits geschrieben hat, ist Abfangen und Ignorieren oft die korrekte Behandlung.

4. Behalte INSERT, wenn du dich auf Eindeutigkeit verlässt — die Exception ist dein Create-only-Guard, das PartiQL-Äquivalent zu attribute_not_exists() auf einer PutItem-Bedingung.

Statements gegen echte Daten auszuprobieren ist der schnellste Weg, die INSERT/UPDATE-Aufteilung zu verinnerlichen — die DynoTable-Desktop-App führt PartiQL in einer SQL-Workbench gegen deine Live-Tabellen aus, und der DynamoDB Expression Builder gibt die äquivalenten nativen API-Anfragen aus, wenn du stattdessen PutItem-Semantik brauchst.

Verwandte Fehler

• ConditionalCheckFailedException — der native-API-Zwilling: attribute_not_exists()-Guard, der bei PutItem fehlschlägt.
• ValidationException: Unexpected from source — die andere häufige PartiQL-Abweisung.
• Learn: PartiQL examples · PartiQL vs SQL

References

• ExecuteStatement — Amazon DynamoDB API Reference (DuplicateItemException)
• PartiQL insert statements for DynamoDB — Developer Guide
• PartiQL update statements for DynamoDB — Developer Guide

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