DynamoDB SerializationException

요약 — DynamoDB가 요청 본문을 와이어 형식에 대해 역직렬화할 수 없었습니다. 거의 항상 타입 래퍼 불일치입니다: 숫자를 {"S": …} 문자열 래퍼 안에 보냄(또는 그 반대), 타입이 지정된 AttributeValue로 전혀 감싸지지 않은 값, 또는 실제 값과 일치하지 않는 저수준 {S,N,BOOL,…} 형태. 타입 감싸기를 고치거나 — Document Client를 사용해 대신 처리되게 하세요.

무엇을 의미하는가

SerializationException: NUMBER_VALUE cannot be converted to String
SerializationException: Start of structure or map found where not expected

요청이 파싱된 후에 발생하는 ValidationException과 달리, SerializationException은 DynamoDB가 요청 본문 자체를 읽는 데 실패했다는 뜻입니다 — JSON 구조나 타입이 지정된 AttributeValue가 DynamoDB가 예상한 타입으로 역직렬화되지 않았습니다. 다른 클라이언트 오류와 마찬가지로 HTTP 400 계열 상태로 돌아오며 재시도할 수 없습니다 — 같은 본문을 재전송하면 재현됩니다.

왜 발생하는가

• 숫자를 문자열 래퍼로 보냄 — 속성이나 키가 숫자(N)로 정의된 곳에 {"S": "123"} 아래 숫자 값을 넣거나 그 반대. 고전적 메시지는 NUMBER_VALUE cannot be converted to String입니다.
• 타입 래퍼 누락 — 저수준 DynamoDBClient로 {pk: {S: "USER#1"}} 대신 원시 {pk: "USER#1"}을 전달. 저수준 API는 모든 값이 타입이 지정된 AttributeValue여야 합니다.
• 키의 잘못된 타입 — 키 속성의 {S}/{N} 래퍼가 테이블의 선언된 키 타입과 일치하지 않음.
• 잘못된 형식의 AttributeValue JSON을 방출하는 수동으로 만든 요청(또는 본문을 재구성하는 프록시 / Lambda).
• 마셜링 라이브러리 혼동 — 이미 마셜링된 DynamoDB JSON을 다시 마셜링하는 클라이언트에 공급(이중 감싸기).

어떻게 해결하는가

1. Document Client를 사용하세요(@aws-sdk/lib-dynamodb, 또는 boto3의 resource('dynamodb')). 네이티브 값을 타입이 지정된 AttributeValue로 대신 마셜링하므로 래퍼 실수의 전체 부류를 제거합니다.
2. 저수준 클라이언트를 사용해야 한다면 모든 값을 감싸세요 — 문자열은 {S: "…"}, 숫자는 {N: "123"}(참고: N은 와이어에서 항상 문자열), {BOOL: true}, {L: […]}, {M: {…}}.
3. 키 타입을 스키마와 일치시키세요 — N으로 정의된 키는 {N: "…"}로 보내야 하며 절대 {S: …}가 아닙니다.
4. 이중 마셜링하지 마세요 — 네이티브 객체를 Document Client에, 또는 이미 타입이 지정된 AttributeValue를 저수준 클라이언트에 전달하고, 절대 섞지 마세요.

Document Client 위에 구축하고 원시 AttributeValue를 다시 건드리지 않나요? DynoTable의 항목 편집기는 모든 속성 옆에 타입이 지정된 값을 보여주고 — DynamoDB-JSON 모드는 정확한 와이어 형태를 드러냅니다 — 그래서 잘못 입력된 숫자나 문자열이 한눈에 명백합니다.

FAQ

DynamoDB에서 SerializationException은 무엇 때문에 발생하나요? 요청 본문이 DynamoDB의 와이어 형식에 대해 역직렬화되지 않았습니다 — 거의 항상 타입 래퍼 불일치로, 숫자를 문자열({"S"}) 래퍼 안에 보내거나, 타입이 지정된 AttributeValue({S}/{N}/…)가 필요한 저수준 클라이언트에 원시 값을 전달하는 것 같은.

SerializationException은 ValidationException과 어떻게 다른가요? SerializationException은 DynamoDB가 요청의 의미를 검증하기 전에 요청 본문을 파싱하는 동안 발생합니다. ValidationException은 파싱 후 올바른 형식의 요청이 규칙을 위반할 때(잘못된 표현식, 키 불일치, 크기 한도) 발생합니다.

관련 오류

• The provided key element does not match the schema — 검증 시 잡힌 키 타입 불일치.
• ValidationException (개요)
• 학습: DynamoDB data types · JSON marshalling

참고 자료

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

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