ItemCollectionSizeLimitExceededException
AWS ItemCollectionSizeLimitExceededException means a DynamoDB item collection exceeded the 10 GB limit for a local secondary index partition key (HTTP 400).
Last reviewed: February 14, 2026|Source-backed guidance under our editorial policy
Start Here
Use the closest compare guide, playbook, or adjacent error page to narrow the decision faster before you start changing production systems.
This page is part of the Error Reference library. Learn more about the project or report a correction.
What Does Item Collection Size Limit Exceeded Exception Mean?
DynamoDB blocks writes for partition keys whose LSI item collection exceeded the hard 10 GB limit, so this is a data-model ceiling rather than a retryable throttle.
Common Causes
- -A local secondary index is defined on a partition key with heavy skew toward one key value.
- -Too many items accumulate under the same partition key, pushing that item collection above 10 GB.
- -Projected attributes and write patterns grow item-collection size faster than expected.
- -Data model lacks sharding or alternate access patterns for unbounded per-key growth.
How to Fix Item Collection Size Limit Exceeded Exception
- 1Identify the hot partition key values causing item-collection growth.
- 2Stop or reroute writes that continue inflating the oversized item collection.
- 3Redesign the data model: shard partition keys or move access pattern to a GSI-based approach.
- 4Do not rely on AWS Support for limit increases; this 10 GB LSI item-collection cap is a hard model constraint.
Step-by-Step Diagnosis for Item Collection Size Limit Exceeded Exception
- 1Confirm the table uses a local secondary index and the failing write targets that indexed partition key.
- 2Use write-path logs and key distribution analysis to isolate top partition key contributors.
- 3Capture item collection metrics on write operations to estimate per-key growth trend.
- 4Validate whether a GSI or key-sharding strategy can preserve query requirements without LSI key-size pressure.
LSI Item-Collection Growth Analysis
- -Identify top partition keys by item-collection growth where LSI is present (example: one tenant key accumulates years of events under a single partition key).
- -Measure projected attribute footprint that accelerates LSI collection growth (example: newly projected blob attribute doubles per-item indexed size).
Data Model Remediation Planning
- -Evaluate key sharding strategy for unbounded entity growth (example: split
customer#123intocustomer#123#2026Q1,...Q2). - -Validate migration path from LSI-dependent access pattern to GSI/query redesign (example: move historical reads to time-bucketed GSI to keep per-key collection bounded).
Seen in Production
Single-tenant key accumulates unbounded history under an LSI
Frequency: common
Example: All events for one customer are written to one partition key and item collection grows past 10 GB.
Fix: Shard the logical key or redesign read patterns to use a GSI strategy that avoids LSI item-collection saturation.
Projected attributes in LSI inflate per-key size unexpectedly
Frequency: rare
Example: New projected fields increase item-collection size for a hot partition key and writes start failing.
Fix: Reduce projection footprint, archive stale items, and rebalance key design before growth crosses limit again.
Debugging Tools
- -DynamoDB ReturnItemCollectionMetrics on writes
- -CloudWatch write/error metrics for affected table
- -Partition-key distribution analysis from application logs
- -Data-model simulation tests for key growth bounds
How to Verify the Fix
- -Re-run previously failing writes for impacted partition keys and confirm the exception is gone.
- -Verify per-key growth stays below LSI item-collection safety thresholds over time.
- -Confirm downstream queries still meet latency and correctness expectations after model changes.
How to Prevent Recurrence
- -Design partition keys for high cardinality and bounded per-key growth when using LSIs.
- -Prefer GSI or sharded-key patterns for workloads with unbounded item growth per logical entity.
- -Continuously monitor key-skew and item-collection growth signals in write-heavy partitions.
Pro Tip
- -set automated alarms on rising item-collection metrics per hot key and trigger archival/sharding workflows before any key approaches LSI limit risk.
Official References
Provider Context
This guidance is specific to AWS services. Always validate implementation details against official provider documentation before deploying to production.