Nesting Levels have exceeded supported limits

TL;DR — DynamoDB lets you nest document types (map M and list L) inside each other up to 32 levels deep. A structure that goes deeper is rejected with a ValidationException. Flatten the data model, split the deep branch into a separate item, or store the over-deep sub-tree as a single serialized string.

What it means

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

(That's the wording AWS documents for this validation failure; the exact phrasing can vary slightly by operation.) An attribute value can be a scalar, or a map/list that itself contains more values — and DynamoDB caps that nesting at 32 levels. The same ceiling applies to expressions: the maximum depth for a document path is 32, so you can't reference deeper than that either. The limit counts the depth of the maps and lists, not the number of attributes. Exceeding it is an HTTP 400 ValidationException, caught at validation time, and not retryable until the document is restructured.

Why it happens

Deeply recursive data — tree/graph structures (org charts, comment threads, nested categories) serialized as maps within maps beyond 32 levels.
A generic serializer — code that marshals arbitrary nested JSON straight into DynamoDB document types without a depth guard.
Accidental self-nesting — a bug that wraps an item inside itself repeatedly.
Migrated documents from a document database whose nesting was never bounded.

How to fix it

Flatten the model — hoist deep sub-structures into top-level attributes or a composite-key layout instead of ever-deeper maps.
Split into multiple items — model the deep branch as separate items under the same partition key (the single-table adjacency pattern).
Serialize the deep sub-tree — store the over-deep portion as one JSON string attribute (opaque to DynamoDB, so its internal depth no longer counts) if you don't need to query into it.
Add a depth guard in your marshalling layer so documents can't silently grow past the limit.
Measure depth before write. Walk the document tree in your serializer and reject anything above 30 levels — leave headroom for one more update path.

Measure in DynoTable

Inspect nested attributes in DynoTable before you write them — open an item with ⌘K and expand map/list fields in the JSON viewer to see how deep the structure runs. Staging (⌘S) lets you preview a put/update and catch depth errors before commit.

Use the item size calculator alongside depth checks — deep nesting often pushes items toward the 400 KB cap too. Switch profiles with ⌘P when testing against Local vs AWS. Setup: Connect to AWS, Install.

Sources

Constraints in Amazon DynamoDB (verified 2026-07-13)
Referring to item attributes when using expressions (verified 2026-07-13)

Item size has exceeded the maximum allowed size — the separate 400 KB whole-item limit.
An expression attribute name used in the document path is not defined — a document-path reference error.
ValidationException (overview)
Learn: DynamoDB data types

References

Last verified 2026-07-13 against the official AWS documentation linked above.