Document nesting is too deep
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: Document nesting is too deep. Maximum nesting depth is 32.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 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.
Related errors
- 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)