ValidationException: Item size has exceeded the maximum allowed size

TL;DR — 一個 DynamoDB 項目最多 400 KB（屬性名稱加上值合計）。你的寫入把某個項目推過了這條線。把大型欄位搬出去（放到 S3，或拆分到多個項目），改為儲存一個參照。

這是什麼意思

ValidationException: Item size has exceeded the maximum allowed size

限制是 400 KB = 409,600 位元組。它計算的是整個項目：每個屬性名稱加上它的值，以 UTF-8 編碼，包含巢狀 map／list 的額外負擔。一個把既有項目撐過 400 KB 的 UpdateItem 也會以同樣方式失敗（作為更新時，訊息會是「Item size to update has exceeded the maximum allowed size」）。

為什麼會發生

把大型 blob 直接內嵌儲存 — base64 圖片、PDF、龐大的 JSON 文件。
一個無界的 list／map（只增不減的陣列、事件記錄）隨時間成長，直到越過 400 KB。
冗長的屬性名稱在一個大項目中被乘上許多次。
在單一項目中反正規化了太多資料。

如何修正

把大型值卸載到 S3。 把物件存在 S3，DynamoDB 中只保留 key／URL。這是任何逼近上限的資料的標準做法。
把資料拆分到多個項目。 使用項目集合／垂直分割模式 — 一個邏輯實體以多個共用分割區索引鍵的項目呈現。
替持續成長的集合設上限。 別讓單一項目累積一個無界的 list；把條目滾動成以排序索引鍵定位的子項目。
如果 S3 不是選項，就在儲存前壓縮真正龐大的文字（gzip → 二進位屬性）。

範例 — 參照模式

// Instead of storing the blob inline, store an S3 pointer:
await doc.send(
  new PutCommand({
    TableName: 'Documents',
    Item: {
      pk: 'DOC#1',
      title: 'Q3 report',
      s3Key: 'documents/DOC#1/report.pdf', // the bytes live in S3
      sizeBytes: 2_400_000
    }
  })
);

常見問題

DynamoDB 的項目大小上限是多少？ 每個項目 400 KB（409,600 位元組），計算每個屬性名稱加上它的值，以 UTF-8 編碼，包含巢狀 map 與 list 的額外負擔。一個把既有項目撐過 400 KB 的 UpdateItem 也會以同樣的錯誤失敗。

我要怎麼在 DynamoDB 中儲存超過 400 KB 的資料？ 把大型值卸載到 S3，DynamoDB 中只保留 key 或 URL；把資料拆分到多個共用分割區索引鍵的項目；或把大型文字壓縮成二進位屬性。別讓單一項目累積一個無界的 list。

重現方式

一個帶有 410 KB 字串屬性的單一項目，剛好超過 400 KB 的天花板：

await client.send(
  new PutItemCommand({
    TableName: 'orders',
    Item: {pk: {S: 'BIG'}, sk: {S: 'META'}, blob: {S: 'x'.repeat(410 * 1024)}}
  })
);

實際輸出：

ValidationException: Item size has exceeded the maximum allowed size
HTTP 400

這則訊息從不告訴你超出多少，也不說是哪個屬性造成的 — 所以當一個項目是由多個來源組成時，請在寫入前先量測，而不是在被拒絕之後才二分搜尋。

參考資料

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

已於 2026-07-26 對照 DynamoDB Local 2.x 與 AWS SDK for JavaScript v3.1095.0 重現 — 上方輸出為逐字原文。