Error: DynamoDB Duplicate Key Error

DynamoDB does not reject every duplicate primary key. PutItem replaces the existing item at that full key unless a condition prevents it. Duplicate targets inside a batch or transaction are a different validation problem.

import { DynamoDBClient } from "@aws-sdk/client-dynamodb";
import { DynamoDBDocumentClient, PutCommand } from "@aws-sdk/lib-dynamodb";

const db = DynamoDBDocumentClient.from(new DynamoDBClient({}));

await db.send(new PutCommand({
  TableName: "Orders",
  Item: { pk: "CUSTOMER#123", sk: "ORDER#42", status: "NEW" },
  ConditionExpression: "attribute_not_exists(pk)",
}));

This is an atomic create-only write: an existing item at the complete primary key causes ConditionalCheckFailedException. A separate read-before-write check is vulnerable to races. Items can share the partition key when their sort keys differ.

BatchWriteItem rejects multiple operations targeting the same item in one request. Deduplicate by the full table primary key and choose deliberately which write should win. Transactions likewise cannot contain multiple actions on the same item. Secondary-index key values do not enforce uniqueness, so a duplicate GSI key is not automatically an error.

See conditional creates and AWS documentation.