Nesting Levels have exceeded supported limits

TL;DR — DynamoDB 让你把文档类型（map M 和 list L）互相嵌套至多 32 层深。更深的结构会被以一个 ValidationException 拒绝。扁平化数据模型、把深层分支拆成一个单独的项目，或者把过深的子树存储为单个序列化字符串。

含义

ValidationException: 1 validation error detected: Nesting Levels have exceeded supported limits

# what the engine actually returns, reproduced against DynamoDB Local:
ValidationException: 1 validation error detected: Nesting Levels have exceeded supported limits: Attributes in the item have nested levels beyond supported limit

（这是 AWS 为这个验证失败记载的措辞；确切的表述可能因操作略有不同。）一个属性值可以是一个标量，或者一个本身包含更多值的 map/list——而 DynamoDB 把这种嵌套限制在 32 层。同样的上限适用于表达式：文档路径的最大深度为 32，因此你也不能引用比那更深的地方。这个限制计算 map 和 list 的深度，而不是属性的数量。超过它是一个 HTTP 400 ValidationException，在验证时被捕获，在文档被重构之前不可重试。

为什么会发生

• 深度递归的数据——被序列化为 map 套 map 超过 32 层的树/图结构（组织架构图、评论线程、嵌套分类）。
• 一个通用的序列化器——把任意嵌套的 JSON 直接 marshal 进 DynamoDB 文档类型而没有深度守卫的代码。
• 意外的自嵌套——一个反复把项目包进它自身的 bug。
• 从文档数据库迁移来的文档，其嵌套从未被限制。

如何修复

1. 扁平化模型——把深层子结构提升为顶层属性或一个复合键布局，而不是越来越深的 map。
2. 拆成多个项目——把深层分支建模为同一个分区键下的独立项目（单表邻接模式）。
3. 序列化深层子树——如果你不需要查询它，就把过深的部分存储为一个 JSON 字符串属性（对 DynamoDB 而言是不透明的，因此它的内部深度不再计入）。
4. 在你的 marshal 层添加一个深度守卫，让文档不会悄悄增长过限制。

在 DynoTable 中测量

在写入之前检查 DynoTable 中的嵌套属性 - 使用 ⌘K 打开项目并在 JSON 查看器中展开映射/列表字段以查看结构的运行深度。暂存 (⌘S) 允许你在提交之前预览放置/更新并捕获深度错误。将 item size calculator 与深度检查一起使用 - 深度嵌套通常也会将项目推向 400 KB 上限。在针对 Local 与 AWS 进行测试时，使用 ⌘P 切换配置文件。设置：连接 AWS、安装。

来源

• Constraints in Amazon DynamoDB（2026-07-13 验证）
• Referring to item attributes when using expressions（2026-07-13 验证）

相关错误

• Item size has exceeded the maximum allowed size——单独的 400 KB 整项目限制。
• An expression attribute name used in the document path is not defined——一个文档路径引用错误。
• ValidationException (overview)
• 学习：DynamoDB data types

参考资料

• Constraints in Amazon DynamoDB — Amazon DynamoDB Developer Guide
• TransactWriteItems — Amazon DynamoDB API Reference
• Referring to item attributes when using expressions in DynamoDB — Amazon DynamoDB Developer Guide
• Error handling with DynamoDB — Amazon DynamoDB Developer Guide

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