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 官方文件。