DynamoDB SerializationException

TL;DR — 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 級狀態回傳，且不可重試 — 重送相同的主體會重現它。

為什麼會發生

數字被送成字串包裝 — 你把數值放在 {"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 的用戶端（雙重包裝）。

如何修正

使用 Document Client（@aws-sdk/lib-dynamodb，或 boto3 的 resource('dynamodb')）。它為你將原生值 marshal 成帶型別的 AttributeValue，這消除了整類包裝錯誤。
若你必須使用低階用戶端，包裝每個值 — 字串用 {S: "…"}、數字用 {N: "123"}（注意：N 在線路上總是字串）、{BOOL: true}、{L: […]}、{M: {…}}。
讓鍵型別符合 schema — 定義為 N 的鍵必須送成 {N: "…"}，絕不 {S: …}。
不要雙重 marshal — 將原生物件傳給 Document Client，或將已帶型別的 AttributeValue 傳給低階用戶端，絕不混用。

建立在 Document Client 上，再也不碰原始 AttributeValue？DynoTable 的項目編輯器在每個屬性旁顯示帶型別的值 — 它的 DynamoDB-JSON 模式會揭示確切的線路格式 — 因此拼錯的數字或字串一眼可見。

常見問題

DynamoDB 中的 SerializationException 是什麼原因造成的？ 請求主體未對照 DynamoDB 的線路格式反序列化 — 幾乎總是型別包裝不符，例如數字被送在字串（{"S"}）包裝中，或原始值被傳給需要帶型別 AttributeValue（{S}/{N}/…）的低階用戶端。

SerializationException 與 ValidationException 有何不同？ SerializationException 發生在 DynamoDB 解析請求主體時，在它驗證請求的含義之前。ValidationException 發生在解析後，當格式良好的請求破壞了某條規則時（錯誤的 expression、鍵不符、大小限制）。

參考資料

最後驗證於 2026-07-13，對照上方連結的 AWS 官方文件。