DynamoDB ItemCollectionSizeLimitExceeded: 10 GB LSI Limit
This error means a partition key's item collection exceeded 10 GB because the table has a Local Secondary Index. Why it happens and how to design around it.
On this page
ItemCollectionSizeLimitExceededException is a niche but hard-stop error with a very specific cause:
ItemCollectionSizeLimitExceededException: Item collection size limit exceededIt means one partition key’s item collection has grown past 10 GB, and it only ever happens on tables that have a Local Secondary Index (LSI).
What is an “item collection”?
An item collection is all the items that share the same partition key — the base-table item plus every LSI entry projected from those items. On a table with an LSI, DynamoDB stores that whole collection together on a single partition, and a single partition maxes out at 10 GB. Cross that and every further write to that partition key fails with this exception (the base item and its LSI projections all count toward the 10 GB).
Tables without an LSI have no such limit — a partition key can hold effectively unlimited data because DynamoDB is free to split it across partitions. The 10 GB ceiling is the price of the LSI’s strong-consistency, same-partition guarantee. See Secondary indexes for the LSI-vs-GSI trade-offs.
Why it’s easy to hit by accident
- A partition key that’s too coarse — e.g. keying by
tenantIdwhen one tenant has millions of rows, or by a status that most items share. - Large items combined with many items per partition key.
- Growth over time: the design was fine at launch and silently crept past 10 GB in production.
How to see how close you are
Query and Scan can return ReturnItemCollectionMetrics: "SIZE", and write operations return ItemCollectionMetrics with a SizeEstimateRangeGB for the affected collection. Watch that estimate — if a collection is trending toward the ceiling, act before it hits.
"ItemCollectionMetrics": {
"ItemCollectionKey": { "pk": { "S": "TENANT#acme" } },
"SizeEstimateRangeGB": [ 8.0, 9.0 ]
}The fixes (all require design changes)
1. Use a GSI instead of an LSI
A Global Secondary Index has no 10 GB item-collection limit — it’s stored independently and partitioned on its own key. If you don’t strictly need the LSI’s strongly-consistent reads or shared-partition-key semantics, a GSI removes the ceiling entirely. This is the most common fix.
2. Choose a more granular partition key
Make the partition key finer so no single collection approaches 10 GB — add a dimension (e.g. TENANT#acme#2026 instead of TENANT#acme), or shard high-volume keys. This spreads the data across many partitions. See Primary keys and Single-table design.
3. Offload bulk data
Keep hot, queryable attributes in DynamoDB and move large blobs (documents, media, big JSON) to S3, storing only a pointer in the item. Smaller items = more headroom per collection.
The catch: LSIs are create-time only
You cannot add or remove an LSI on an existing table — it’s fixed at creation. So escaping this limit almost always means migrating to a new table with the corrected design (GSI or finer key) and backfilling the data. Plan the partition-key granularity and index type up front; retrofitting is expensive.
Model it before it bites
Item-collection limits are a design-time decision that only shows up in production. Tablyne’s single-table design studio lets you lay out partition keys, indexes and access patterns visually — so you can catch a too-coarse key or an LSI you didn’t need before it hits 10 GB in prod. Download Tablyne free to model your tables safely.
Frequently asked questions
Does the 10 GB item collection limit apply to every DynamoDB table?
No. It applies only to tables that have one or more Local Secondary Indexes (LSIs). Without an LSI, a single partition key can hold an effectively unbounded amount of data. The limit is a direct consequence of how LSIs co-locate index data with the base items.
How do I avoid ItemCollectionSizeLimitExceededException?
Either use a Global Secondary Index instead of a Local Secondary Index (GSIs have no 10 GB collection limit), or choose a more granular partition key so no single collection approaches 10 GB. LSI choice is made at table creation, so plan for it up front.
Can I add or remove an LSI later to fix this?
No. Local Secondary Indexes can only be created at table-creation time and cannot be added or removed afterward. Escaping the limit means migrating to a new table designed with a GSI or a finer partition key.