ValidationException: Item size has exceeded the maximum allowed size

요약 — DynamoDB 항목은 최대 400 KB(속성 이름 + 값을 합한 크기)입니다. 지금의 쓰기가 항목을 그 선 너머로 밀어냅니다. 큰 필드를 밖으로 옮기고(S3로 보내거나 여러 항목으로 쪼개고) 대신 참조를 저장하세요.

무엇을 의미하는가

ValidationException: Item size has exceeded the maximum allowed size

한도는 400 KB = 409,600바이트입니다. 항목 전체를 계산합니다. 모든 속성 이름과 그 값을 UTF-8 인코딩 기준으로, 중첩된 맵/리스트 오버헤드까지 포함합니다. 기존 항목을 400 KB 너머로 키우는 UpdateItem도 같은 방식으로 실패합니다(업데이트일 때 메시지는 "Item size to update has exceeded the maximum allowed size"로 나옵니다).

왜 발생하는가

큰 blob을 인라인으로 저장 — base64 이미지, PDF, 큰 JSON 문서.
시간이 지나며 400 KB를 넘길 때까지 커지는 무한한 리스트/맵(추가 전용 배열, 이벤트 로그).
큰 항목 전반에 걸쳐 반복되는 긴 속성 이름.
하나의 항목에 과도하게 비정규화.

어떻게 해결하는가

큰 값은 S3로 옮기세요. 객체는 S3에 저장하고 DynamoDB에는 키/URL만 두세요. 한도에 근접하는 모든 것에 대한 표준 패턴입니다.
데이터를 여러 항목으로 나누세요. 항목 컬렉션 / 수직 파티션 패턴을 사용하세요 — 하나의 논리적 엔티티를 파티션 키를 공유하는 여러 항목으로 표현합니다.
커지는 컬렉션에 상한을 두세요. 단일 항목이 무한한 리스트를 쌓게 두지 말고, 항목들을 정렬 키로 구분되는 자식 항목으로 넘기세요.
S3가 선택지가 아니라면 정말로 큰 텍스트는 저장 전에 압축하세요(gzip → 바이너리 속성).

예제 — 참조 패턴

// Instead of storing the blob inline, store an S3 pointer:
await doc.send(
  new PutCommand({
    TableName: 'Documents',
    Item: {
      pk: 'DOC#1',
      title: 'Q3 report',
      s3Key: 'documents/DOC#1/report.pdf', // the bytes live in S3
      sizeBytes: 2_400_000
    }
  })
);

FAQ

DynamoDB의 최대 항목 크기는 얼마인가요? 항목당 400 KB(409,600바이트)이며, 모든 속성 이름과 그 값을 UTF-8 인코딩 기준으로, 중첩된 맵과 리스트 오버헤드까지 포함해 계산합니다. 기존 항목을 400 KB 너머로 키우는 UpdateItem도 같은 오류로 실패합니다.

DynamoDB에 400 KB보다 큰 데이터를 저장하려면 어떻게 하나요? 큰 값을 S3로 옮기고 DynamoDB에는 키나 URL만 두거나, 파티션 키를 공유하는 여러 항목으로 데이터를 나누거나, 큰 텍스트를 압축해 바이너리 속성으로 저장하세요. 단일 항목이 무한한 리스트를 쌓게 두지 마세요.

재현하기

400 KB 상한을 살짝 넘긴 410 KB 문자열 속성을 담은 단일 항목:

await client.send(
  new PutItemCommand({
    TableName: 'orders',
    Item: {pk: {S: 'BIG'}, sk: {S: 'META'}, blob: {S: 'x'.repeat(410 * 1024)}}
  })
);

실제 출력:

ValidationException: Item size has exceeded the maximum allowed size
HTTP 400

이 메시지는 얼마나 초과했는지도, 어떤 속성 때문인지도 결코 알려 주지 않습니다 — 그러니 여러 소스에서 항목을 조립할 때는 거부된 뒤 이분 탐색으로 찾기보다 쓰기 전에 크기를 재세요.

참고 자료

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

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