Diagnosing and Resolving ProvisionedThroughputExceededException in DynamoDB

The Throughput Bottleneck

A ProvisionedThroughputExceededException occurs when your application requests more Read Capacity Units (RCU) or Write Capacity Units (WCU) than are currently available for a table or its Global Secondary Indexes (GSIs). The critical takeaway is that increasing total table capacity does not always stop throttling; if your traffic is concentrated on a single partition key, you are facing a "hot partition" problem that requires a data model change rather than a slider adjustment.

Identifying the Root Cause

Before changing settings, use this table to match your symptoms to the likely cause.

Symptom	Likely Cause	Diagnostic Metric
Throttling occurs during peak hours across all keys	Insufficient overall provisioned capacity	ConsumedReadCapacityUnits > Provisioned
Throttling occurs even when total usage is low	Hot Partition (Single key overload)	CloudWatch Contributor Insights (Top Keys)
Sudden spikes cause brief errors, then stabilize	Burst Capacity exhaustion	ReadThrottleEvents / WriteThrottleEvents
Throttling starts after deploying a new report/export	Inefficient Scan operations	High ConsumedReadCapacityUnits per request

Step-by-Step Diagnostic Workflow

Execute these checks in order to avoid unnecessary costs associated with over-provisioning.

1. Check CloudWatch Metrics:

   Navigate to the CloudWatch console and monitor ReadThrottleEvents and WriteThrottleEvents. If these spikes correlate exactly with your application errors, you have confirmed a throughput limit issue.

2. Analyze Item Size:

   Review the size of the items being accessed. DynamoDB calculates capacity based on size: 1 WCU is 1 KB for a standard write; 1 RCU is 4 KB for a strongly consistent read. If your items have grown from 2 KB to 10 KB, you are now consuming 5x more capacity per request.

3. Enable Contributor Insights:

   Enable DynamoDB Contributor Insights for the affected table. This tool identifies the specific partition keys experiencing the most traffic. If a small percentage of keys account for the majority of requests, you have a hot partition.

4. Audit Access Patterns:

   Check if the application is using Scan instead of Query. A Scan reads every item in the table, consuming RCUs rapidly regardless of whether the data is needed.

Applying the Fix

Match your fix to the findings from the diagnostic workflow.

Scenario A: General Capacity Shortage

If total consumed capacity consistently exceeds provisioned limits across the whole table:

• Option 1: Increase the provisioned RCU/WCU in the AWS Console or via CLI.
• Option 2: Switch to On-Demand mode. This is ideal for unpredictable workloads but can be more expensive for steady-state, high-volume traffic.

Scenario B: The Hot Partition

If Contributor Insights shows a few keys are causing the bottleneck, increasing total capacity will not help because a single partition has a hard limit (3,000 RCU / 1,000 WCU). Use Write Sharding:

Instead of a partition key like "Status" = "Active", append a random suffix to the key:

# Example of Sharded Key
# Original: Status_Active
# Sharded: Status_Active_1, Status_Active_2, ... Status_Active_10

Your application must then query all 10 shards and aggregate the results in the application layer.

Scenario C: Inefficient Read Patterns

If Scan operations are the cause, rewrite the logic to use Query with a specific partition key and a sort key filter. If you must perform a full table scan for reporting, use a Parallel Scan to distribute the load, but be aware this will consume capacity even faster.

Verification and Limitations

To verify the fix, monitor the ReadThrottleEvents metric. A successful resolution will show these events dropping to zero during the previously problematic time windows.

Limitations: Adaptive capacity automatically redistributes throughput, but it is not instantaneous. It may take several minutes to react to a sudden shift in traffic patterns. Do not rely on it for sub-second spikes.

Rollback Procedure

If you increased provisioned capacity or switched to On-Demand mode and wish to revert to save costs:

1. Navigate to the Capacity tab of the DynamoDB table.
2. Select Provisioned mode.
3. Enter the original RCU/WCU values.
4. Save changes. Note: Reducing capacity too aggressively may re-trigger the ProvisionedThroughputExceededException.