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

TL;DR — 你 Item（或鍵）中的某個屬性有一個內部沒有值的 AttributeValue — 空集合、鍵屬性中的空字串/二進位、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 不同：那個是關於 expression 中的 :placeholder；這個是關於項目主體本身中的屬性（PutItem、BatchWriteItem、TransactWriteItems）。

為什麼會發生

你要寫入的物件中有 undefined/null 欄位 — marshaller 發出一個空的 AttributeValue，而非跳過它或給它 NULL 型別。
空集合 — SS、NS 或 BS 必須至少有一個成員。空集合在任何地方都無效。
鍵屬性中的空字串 — 非鍵字串屬性可以是 ""，但表格或索引的鍵屬性不行。
鍵中的空二進位值 — 與字串同樣的規則：空二進位對非鍵屬性沒問題（在集合、list 與 map 內也是），絕不用於鍵。
埋在你要持久化的 Map 或 List 中的巢狀空集合 — 巢狀的空_字串與二進位值_是允許的；巢狀的空_集合_不是。

如何修正

在寫入前移除空/undefined 屬性。 只從確實有值的欄位建立 Item；捨棄其餘的，而非送出空的包裝。
對 Document Client，啟用空值處理。 @aws-sdk/lib-dynamodb 的 removeUndefinedValues: true marshal 選項會捨棄 undefined 欄位，讓它們永不抵達線路。（非鍵屬性的空字串與二進位值 DynamoDB 直接允許。）
絕不送出空集合 — 當集合沒有成員時完全省略該屬性，或儲存 NULL。
給鍵屬性真實值 — partition/sort key（表格或索引）絕不能是空字串或空二進位。
走遍巢狀 Map/List 尋找散落的空集合，若出錯的屬性不在頂層。

常見問題

DynamoDB 中的 "Supplied AttributeValue is empty" 是什麼意思？ 你項目中的某個屬性有一個不含儲存值的 AttributeValue — 鍵屬性中的空字串或二進位、空集合，或 null/undefined 欄位。每個 AttributeValue 都必須含有恰好一個支援的資料型別，因此 DynamoDB 拒絕該寫入。

我要如何阻止 DynamoDB 拒絕空值？ 在寫入前移除空與 undefined 屬性（或使用 Document Client 的 removeUndefinedValues 選項）。絕不送出空集合 — 省略該屬性或儲存 NULL。鍵屬性必須總是攜帶真實、非空的值。

參考資料

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