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 文档。
一个无界的列表/映射（只追加的数组、事件日志）随时间增长，直到越过 400 KB。
长属性名在一个大项目里被成倍放大。
往单个项目里反规范化了太多东西。

如何修复

把大的值卸载到 S3。把对象存在 S3，DynamoDB 里只保留键/URL。对于任何逼近这个限制的东西，这都是标准做法。
把数据拆到多个项目上。使用项目集合 / 纵向分区模式——一个逻辑实体表现为共享同一个分区键的若干个项目。
给增长中的集合设上限。别让单个项目累积一个无界列表；把条目滚动到按排序键区分的子项目里。
如果 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 里只保留键或 URL；或者把数据拆到共享同一个分区键的多个项目上；又或者把大段文本压缩成一个二进制属性。别让单个项目累积一个无界列表。

复现方法

一个带着 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 复现——上方输出为原样照录。