Provided list of item keys contains duplicates (BatchWriteItem)

요약 — BatchWriteItem 요청에 같은 기본 키에 대한 작업이 두 개 이상 들어 있습니다(같은 키의 put 두 번, 또는 put과 delete). 하나의 배치는 같은 항목에 두 번 이상 작용할 수 없으므로 DynamoDB가 배치 전체를 거부합니다. 보내기 전에 키당 하나의 작업으로 중복을 합치세요.

무엇을 의미하는가

ValidationException: Provided list of item keys contains duplicates

BatchWriteItem은 최대 25개의 put/delete 작업을 수행합니다. 요청 안의 모든 작업은 서로 다른 기본 키를 대상으로 해야 합니다. 두 개의 PutRequest/DeleteRequest 항목이 같은 키(파티션 키, 또는 파티션 + 정렬 키)로 해석되면 DynamoDB는 이 HTTP 400 ValidationException으로 호출 전체를 실패시키며, 아무것도 기록되지 않습니다. 그대로는 재시도할 수 없습니다.

왜 발생하는가

하나의 배치에서 같은 항목을 두 번 put — 소스 목록에 중복 레코드가 있는데 각각을 PutRequest로 매핑할 때 흔합니다.
같은 배치에서 같은 키의 put과 delete — 여전히 한 항목에 대한 두 작업이므로 거부됩니다.
키가 반복되는 이벤트 스트림에서 중복 제거 없이 배치를 구성하는 경우.
복합 키를 간과 — 서로 다르다고 생각한 두 행이 파티션 + 정렬 키를 공유하는 경우.
청크로 나누기 전에 키 기준으로 병합하지 않는 ETL / 대량 로드 작업(Glue, 자체 임포터).

어떻게 해결하는가

키당 하나의 작업으로 합치고, 마지막 쓰기가 이기게 하세요:

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

Python batch_writer를 쓴다면 boto3의 overwrite_by_pkeys를 사용하세요 — batch_writer(overwrite_by_pkeys=['pk', 'sk'])는 새로 추가된 항목이 같은 기본 키를 가질 때 버퍼에 있던 요청을 버리므로, 각 키에 대해 마지막 쓰기가 이깁니다.
중복을 제거한 뒤 BatchWriteItem당 25개 작업으로 청크를 나누고, UnprocessedItems를 재시도하세요(스로틀링 — 별개의 문제입니다).
같은 키를 쓰고 나서 삭제해야 하나요? 별도의 요청으로 나누거나 TransactWriteItems를 사용하세요(이것 역시 한 항목에 대한 두 작업을 금지하지만 의도가 명확해집니다).

대량 로드를 실행하기 전에 살펴보고 싶으신가요? DynoTable 데스크톱 앱은 항목을 키별로 보여 주므로 같은 배치에 들어갈 중복 키가 눈에 띕니다.

재현하기

같은 기본 키가 두 번 들어 있는 BatchWriteItem:

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

실제 출력:

ValidationException: Provided list of item keys contains duplicates
HTTP 400

배치 전체가 거부되어 어느 쓰기도 반영되지 않습니다. 배치에는 순서 보장이 없기 때문에 DynamoDB는 두 중복 중 무엇이 이겨야 할지 결정하지 않습니다. 따라서 요청을 만들기 전에 키 기준으로 중복을 제거하세요.

참고 자료

위에 링크된 공식 AWS 문서를 기준으로 2026-07-13에 마지막으로 검증했습니다.

2026-07-26에 DynamoDB Local 2.x와 AWS SDK for JavaScript v3.1095.0으로 재현했습니다 — 위 출력은 그대로 옮긴 것입니다.