DynamoDB SerializationException

TL;DR — DynamoDB 无法根据其传输格式反序列化请求体。几乎总是一个类型包裹不匹配：一个数字被放进了一个 {"S": …} 字符串包裹（或反之）、一个根本没有被包进带类型 AttributeValue 的值，或者一个与实际值不匹配的底层 {S,N,BOOL,…} 形态。修正类型包裹——或者使用文档客户端，让它为你处理。

含义

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 类状态返回，且不可重试——重发同样的请求体会重现它。

为什么会发生

数字作为字符串包裹发送——你把一个数值放进了 {"S": "123"}，而该属性或键被定义为数字（N），或反之。经典消息是 NUMBER_VALUE cannot be converted to String。
缺少带类型的包裹——用底层 DynamoDBClient 时你传入了一个原始的 {pk: "USER#1"} 而不是 {pk: {S: "USER#1"}}。底层 API 要求每个值都是一个带类型的 AttributeValue。
键中的类型错误——键属性的 {S}/{N} 包裹与表声明的键类型不匹配。
一个手工构建的请求（或一个重塑请求体的代理/Lambda）发出了格式错误的 AttributeValue JSON。
marshal 库的混淆——把已经 marshal 过的 DynamoDB JSON 喂给一个会再次 marshal 的客户端（双重包裹）。

如何修复

使用文档客户端（@aws-sdk/lib-dynamodb，或 boto3 的 resource('dynamodb')）。它为你把原生值 marshal 成带类型的 AttributeValue，消除了整类包裹错误。
如果你必须使用底层客户端，就包裹每个值——字符串用 {S: "…"}，数字用 {N: "123"}（注意：N 在传输时总是一个字符串）、{BOOL: true}、{L: […]}、{M: {…}}。
让键类型与模式匹配——一个定义为 N 的键必须作为 {N: "…"} 发送，绝不用 {S: …}。
不要双重 marshal——把原生对象传给文档客户端，或把已经带类型的 AttributeValue 传给底层客户端，绝不混用。

在文档客户端之上构建，再也不碰原始 AttributeValue？DynoTable 的项目编辑器在每个属性旁边显示带类型的值——其 DynamoDB-JSON 模式会揭示确切的传输形态——因此一个类型弄错的数字或字符串一眼就能看出。

常见问题

是什么导致了 DynamoDB 中的 SerializationException？ 请求体没有根据 DynamoDB 的传输格式反序列化——几乎总是一个类型包裹不匹配，例如一个数字被放进了字符串（{"S"}）包裹，或者一个原始值被传给了要求带类型 AttributeValue（{S}/{N}/…）的底层客户端。

SerializationException 与 ValidationException 有何不同？ SerializationException 发生在 DynamoDB 解析请求体时，在它验证请求含义之前。ValidationException 发生在解析之后，当一个格式良好的请求违反了某条规则时（错误的表达式、键不匹配、大小限制）。

参考资料

最后核实于 2026-07-13，依据上方链接的 AWS 官方文档。