Supplied AttributeValue is empty, must contain exactly one of the supported datatypes

요약 — Item(또는 키)의 속성 중 하나가 안에 값이 없는 AttributeValue를 가집니다 — 빈 set, 키 속성의 빈 문자열/바이너리, null/undefined 필드, 또는 S/N/BOOL/… 멤버가 없는 래퍼. DynamoDB는 모든 AttributeValue가 정확히 하나의 지원되는 타입을 지니기를 요구합니다. 빈 속성을 제거하거나 실제 값을 주세요.

무엇을 의미하는가

ValidationException: Supplied AttributeValue is empty, must contain exactly one of the supported datatypes

DynamoDB가 항목의 형태를 검증하는 동안 요청을 거부했습니다: AttributeValue가 존재했지만 DynamoDB가 저장할 수 있는 것을 아무것도 지니지 않았습니다. 모든 AttributeValue는 정확히 하나의 타입이 지정된 값(S, N, B, SS, NS, BS, M, L, NULL, 또는 BOOL)을 포함해야 합니다. HTTP 400이며 재시도할 수 없습니다 — 속성을 고칠 때까지 같은 항목이 다시 실패합니다.

이것은 ExpressionAttributeValues contains invalid value와 구별됩니다: 그것은 표현식의 :placeholder에 대한 것이고, 이것은 항목 본문 자체(PutItem, BatchWriteItem, TransactWriteItems)의 속성에 대한 것입니다.

왜 발생하는가

• 쓰는 객체의 undefined/null 필드 — 마셜러가 이를 건너뛰거나 NULL 타입으로 지정하는 대신 빈 AttributeValue를 방출합니다.
• 빈 Set — SS, NS, 또는 BS는 최소 하나의 멤버가 있어야 합니다. 빈 set은 어디서나 유효하지 않습니다.
• 키 속성의 빈 문자열 — 키가 아닌 문자열 속성은 ""일 수 있지만, 테이블이나 인덱스 키 속성은 안 됩니다.
• 키의 빈 바이너리 값 — 문자열과 같은 규칙: 빈 바이너리는 키가 아닌 속성(그리고 set, list, map 내부)에는 괜찮고, 키에는 절대 안 됩니다.
• 지속하는 Map이나 List 안에 묻힌 중첩 빈 set — 중첩 빈 문자열과 바이너리 값 은 허용되지만, 중첩 빈 set 은 안 됩니다.

어떻게 해결하는가

1. 쓰기 전에 빈/undefined 속성을 제거하세요. 실제로 값이 있는 필드만으로 Item을 만들고, 빈 래퍼를 보내는 대신 나머지를 버리세요.
2. Document Client의 경우 빈 값 처리를 활성화하세요. @aws-sdk/lib-dynamodb의 removeUndefinedValues: true 마셜링 옵션은 undefined 필드를 버려 와이어에 도달하지 않게 합니다. (키가 아닌 속성의 빈 문자열과 바이너리 값은 DynamoDB가 직접 허용합니다.)
3. 절대 빈 Set을 보내지 마세요 — set에 멤버가 없으면 속성을 완전히 생략하거나 NULL을 저장하세요.
4. 키 속성에 실제 값을 주세요 — 파티션/정렬 키(테이블 또는 인덱스)는 절대 빈 문자열이나 빈 바이너리일 수 없습니다.
5. 문제의 속성이 최상위가 아니면 떠도는 빈 set을 찾기 위해 중첩 Map/List를 훑으세요.

FAQ

DynamoDB에서 "Supplied AttributeValue is empty"는 무슨 뜻인가요? 항목의 속성이 저장된 값을 포함하지 않는 AttributeValue를 가집니다 — 키 속성의 빈 문자열이나 바이너리, 빈 Set, 또는 null/undefined 필드. 모든 AttributeValue는 정확히 하나의 지원되는 데이터 타입을 포함해야 하므로 DynamoDB가 쓰기를 거부합니다.

DynamoDB가 빈 값을 거부하지 않게 하려면 어떻게 하나요? 쓰기 전에 빈 속성과 undefined 속성을 제거하세요(또는 Document Client의 removeUndefinedValues 옵션을 사용). 절대 빈 Set을 보내지 마세요 — 속성을 생략하거나 NULL을 저장하세요. 키 속성은 항상 실제의 비어 있지 않은 값을 지녀야 합니다.

관련 오류

• ExpressionAttributeValues contains invalid value — 표현식 플레이스홀더에서의 동일한 부류의 문제.
• ValidationException (개요)
• 학습: DynamoDB data types · JSON marshalling

참고 자료

• Supported data types and naming rules in Amazon DynamoDB — Amazon DynamoDB Developer Guide
• AttributeValue — Amazon DynamoDB API Reference
• Error handling with DynamoDB — Amazon DynamoDB Developer Guide

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