1- Key range throughput exceeded (hot partitions)

DynamoDB partition limits and effective partition key design addressing hot partition prevention, see Best practices for designing and using partition keys effectively in DynamoDB.

General partition concepts and data distribution, see Partitions in DynamoDB.

Additional guidance and real-world scenarios for managing partition keys and throughput, see Additional resources.

DynamoDB often adapts to hot partitions through its automatic split-for-heat mechanism. If you see throttling events that stop after a short period, your table may have already adapted by splitting the hot partition. When partitions split, each new partition handles a smaller section of the keyspace, which can help distribute the load more evenly. In many cases, no further action is needed as DynamoDB has automatically resolved the issue.

For more information about the split-for-heat mechanism, see Additional resources.

TableReadKeyRangeThroughputExceeded

TableWriteKeyRangeThroughputExceeded

IndexReadKeyRangeThroughputExceeded

IndexWriteKeyRangeThroughputExceeded

Pre-warm capacity: If throttling persists, check if your table is limited by its Understanding DynamoDB warm throughput capacity. Use warm throughput or increase read provisioned capacity in advance for expected traffic increases. Increasing warm throughput improves your table's ability to handle sudden traffic spikes before throttling occurs. Over time, if your actual throughput consistently approaches the warm throughput levels, DynamoDB may split busy partitions based on observed usage patterns.

Identify your hot keys: If the table didn't resolve it automatically and your warm throughput is high or raising it didn't help, you'll need to identify specific hot keys. Use Identifying hot keys using CloudWatch Contributor Insights to determine if any particular partition key values are hot. This is a first step to target your mitigation efforts effectively. Note that identification may not always be straightforward, particularly with rolling hot partitions (where different partitions become hot over time) or when throttling is triggered by operations like scans. For these complex scenarios, you may need to analyze your application's access patterns and correlate them with the timing of throttling events.

Depending on your use case, consider using eventually consistent reads: Switch from strongly consistent to eventually consistent reads, which consume half the RCUs and can immediately double your effective read capacity. For best practices on implementing eventually consistent reads to reduce read capacity consumption, see DynamoDB read consistency.

Improve partition key design: As a long-term solution, consider Improving partition key design to distribute access more evenly across partitions. This approach often provides the most comprehensive resolution to hot partition issues by addressing the root cause. However, it requires careful planning as it involves significant migration challenges.

Pre-warm capacity: If throttling persists, check if your table is limited by its Understanding DynamoDB warm throughput capacity. Use warm throughput or increase write provisioned capacity in advance for expected traffic increases. Increasing warm throughput improves your table's ability to handle sudden traffic spikes before throttling occurs. Over time, if your actual throughput consistently approaches the warm throughput levels, DynamoDB may split busy partitions based on observed usage patterns.

Identify your hot keys: If the table didn't resolve it automatically and your warm throughput is high or raising it didn't help, you'll need to identify specific hot keys. Use Identifying hot keys using CloudWatch Contributor Insights to determine if any particular partition key values are hot. This is a first step to target your mitigation efforts effectively. Consider these common patterns:

Note that write throttling can also occur with operations like BatchWriteItem or transactions that affect multiple items simultaneously. When individual items within a BatchWriteItem request are throttled, DynamoDB does not propagate these throttling errors to the application code. Instead, DynamoDB returns information about the unprocessed items in the response, which your application must handle by retrying those specific items. For transactions, the entire operation fails with a TransactionCanceledException if any item experiences throttling. For these complex scenarios, you may need to analyze your application's write patterns and data ingestion workflows, correlate them with the timing of throttling events, and implement appropriate retry handling strategies.

Improve partition key design: As a long-term solution, consider Improving partition key design to distribute access more evenly across partitions. This approach often provides the most comprehensive resolution to hot partition issues by addressing the root cause. However, it requires careful planning as it involves significant migration challenges.

Pre-warm capacity: If throttling persists, check if your GSI is limited by its Understanding DynamoDB warm throughput capacity. Use warm throughput or increase read provisioned capacity in advance for expected traffic increases. Increasing warm throughput improves your GSI's ability to handle sudden traffic spikes before throttling occurs. Over time, if your actual throughput consistently approaches the warm throughput levels, DynamoDB may split busy partitions based on observed usage patterns.

Identify your hot keys: If the GSI didn't resolve it automatically and your warm throughput is high or raising it didn't help, you'll need to identify specific hot keys. Use Identifying hot keys using CloudWatch Contributor Insights to determine if any particular partition key values are hot. This is a first step to target your mitigation efforts effectively. Note that for GSIs, the partition key distribution may differ significantly from your base table, creating different hot key patterns.

Redesign GSI partition keys: Consider whether your GSI key design might be creating artificial hot spots (such as status flags, date-only keys, or boolean attributes) that concentrate reads on a small number of partitions. Consider using composite keys that combine the low-cardinality attribute with a high-cardinality attribute (e.g., "ACTIVE#customer123" instead of just "ACTIVE") or apply Using write sharding to distribute workloads evenly in your DynamoDB table techniques to the base table items that affect GSI distribution to distribute writes across multiple partitions. While querying sharded data requires additional application logic to aggregate results, this approach prevents throttling by distributing access patterns more evenly.

Redesign GSI partition key: Review your GSI partition key design to verify it has sufficient cardinality (uniqueness) to distribute writes evenly. A common cause of GSI write throttling is using low-cardinality attributes as GSI partition keys (such as status flags with only a few possible values). Even when your base table has well-distributed partition keys, your GSI can still experience hot partitions if its partition key concentrates writes to a small number of values. For example, if 80% of your items have status="ACTIVE", this creates a severe hot partition in a status-based GSI. Consider using composite keys that combine the low-cardinality attribute with a high-cardinality attribute (e.g., "ACTIVE#customer123" instead of just "ACTIVE") or apply Using write sharding to distribute workloads evenly in your DynamoDB table techniques to the base table items that affect GSI distribution to distribute writes across multiple partitions. While querying sharded data requires additional application logic to aggregate results, this approach prevents throttling by distributing access patterns more evenly.

Pre-warm capacity:Check if your GSI is limited by its Understanding DynamoDB warm throughput capacity. Use warm throughput or increase read provisioned capacity in advance for expected traffic increases. Increasing warm throughput improves your GSI's ability to handle sudden traffic spikes before throttling occurs. Over time, if your actual throughput consistently approaches the warm throughput levels, DynamoDB may split busy partitions based on observed usage patterns.

Optimize GSI projections: Apply Optimizing GSI projections techniques to reduce write volume to GSIs. Projecting fewer attributes can significantly reduce the write capacity consumed by each GSI update.

Partition-level throttling events: ReadKeyRangeThroughputThrottleEvents and WriteKeyRangeThroughputThrottleEvents track when individual partitions exceed their throughput limits. ReadThrottleEvents and WriteThrottleEvents track when any read or write requests exceed the provisioned capacity.

Capacity consumption: ConsumedReadCapacityUnits and ConsumedWriteCapacityUnits show overall usage patterns.

Data migration complexity: Redesigning partition keys requires migrating all existing data, which can be resource-intensive and time-consuming for large tables.

Application code changes: All application code that reads or writes to the table must be updated to use the new key structure.

Production impact: Migrating to a new key design often requires downtime or complex dual-write strategies during transition.

For more information about using GSIs to distribute read traffic, see Using Global Secondary Indexes to create eventually consistent secondary indexes in Amazon DynamoDB.

For hands-on guidance about scaling DynamoDB and managing hot partitions, see Part 1: Scaling DynamoDB - How partitions, hot keys, and split for heat impact performance.

For detailed information about how DynamoDB's split-for-heat mechanism works, its benefits, and implementation details, see Part 3: Summary and best practices.

For detailed write sharding strategies, see Using write sharding to distribute workloads evenly in your DynamoDB table.