2- Provisioned throughput exceeded - Amazon DynamoDB
Provisioned throughput exceeded mitigation measuresCommon diagnosis and monitoringResolution proceduresAdditional resources
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

2- Provisioned throughput exceeded

Provisioned capacity throttling occurs when your application's consumption rate exceeds the read or write capacity units (RCUs/WCUs) configured for your tables or global secondary indexes. While DynamoDB provides burst capacity to handle occasional traffic spikes, sustained requests beyond your provisioned limits result in throttling. When this happens, DynamoDB returns a ProvisionedThroughputExceeded throttling reason type in the throttling exception. The reason identifies whether the issue is with read or write operations and whether it affects the base table or a global secondary index. Throttling can occur regardless of whether auto scaling is enabled.

Provisioned throughput exceeded mitigation measures

This section provides resolution guidance for provisioned capacity throttling scenarios. Before using this guide, ensure you have identified the specific throttling reason from your application's exception handling, and determined the Amazon Resource Name (ARN) of the affected resource. For information on retrieving throttling reasons and identifying throttled resources, see DynamoDB throttling diagnosis framework.

Select a specific throttling reason below to find recommended mitigation options:

TableReadProvisionedThroughputExceeded

When this occurs

Your application's read consumption rate exceeds the provisioned read capacity units (RCUs) configured for your table. You can monitor the CloudWatch metrics in Common diagnosis and monitoring to analyze your throttling event.

Resolution approach

Choose the appropriate strategy based on your table's Auto Scaling configuration:

TableWriteProvisionedThroughputExceeded

When this occurs

Your application's write consumption rate exceeds the provisioned write capacity units (WCUs) configured for your table. You can monitor the CloudWatch metrics in Common diagnosis and monitoring to analyze your throttling event.

Resolution approach

Choose the appropriate strategy based on your table's Auto Scaling configuration:

IndexReadProvisionedThroughputExceeded

When this occurs

Read requests to a Global Secondary Index (GSI) exceed the GSI's provisioned read capacity units (RCUs). You can monitor the CloudWatch metrics in Common diagnosis and monitoring to analyze your throttling event.

Resolution approach

Choose the appropriate strategy based on your GSI's Auto Scaling configuration:

IndexWriteProvisionedThroughputExceeded

When this occurs

Updates to items in the base table trigger writes to a GSI that exceed the GSI's provisioned write capacity. This causes back-pressure throttling on base table writes. You can monitor the CloudWatch metrics in Common diagnosis and monitoring to analyze your throttling event.

Resolution approach

Choose the appropriate strategy based on your GSI's Auto Scaling configuration:

Common diagnosis and monitoring

When troubleshooting throughput errors, several CloudWatch metrics can help identify the root cause.

Essential CloudWatch metrics

Monitor these key metrics to diagnose provisioned capacity throttling:

  • Throttling events: ReadProvisionedThroughputThrottleEvents and WriteProvisionedThroughputThrottleEvents track when requests are throttled. ReadThrottleEvents and WriteThrottleEvents track when any read or write requests exceed the provisioned capacity.

  • Capacity consumption: ConsumedReadCapacityUnits and ConsumedWriteCapacityUnits show actual usage.

  • Provisioned capacity: ProvisionedReadCapacityUnits and ProvisionedWriteCapacityUnits show configured limits.

Analysis approach

Follow these steps to confirm throttling diagnosis:

  1. Compare consumed capacity to provisioned capacity - if consumption consistently approaches or exceeds provisioned limits, this confirms the diagnosis.

  2. Review throttling event frequency and timing to identify patterns.

  3. Use CloudWatch Contributor Insights to identify which items or partition keys consume the most capacity.

For an overview of how to evaluate if you have right-sized provisioning on your DynamoDB tables, see Evaluate your provisioned capacity for right-sized provisioning in your DynamoDB table.

Resolution procedures

Increasing table throughput capacity

Use this procedure when Auto Scaling is not enabled and you need immediate capacity increase.

  1. Update your table's provisioned capacity using the DynamoDB console, Amazon CLI, or SDK:

    • For read capacity: Increase the ReadCapacityUnits parameter, which specifies the maximum number of strongly consistent reads consumed per second before DynamoDB throttles requests.

    • For write capacity: Increase the WriteCapacityUnits parameter, which specifies the maximum number of writes consumed per second before DynamoDB throttles requests.

  2. Ensure that your table's provisioned throughput capacity remains within the per-account and per-table throughput limit in your Region..

Configuring table Auto Scaling to adjust the read or write capacity of your table or GSI

Configure DynamoDB Auto Scaling to automatically adjust read or write capacity based on traffic patterns. You can configure Auto Scaling independently for both tables and GSIs, with separate controls for read and write capacity units.

  1. Enable Auto Scaling for read capacity, write capacity, or both on your table or GSI.

  2. Set a target utilization percentage with headroom for traffic spikes.

    Note

    Lower target utilization increases costs and scaling frequency. Targets below 40% may cause over-provisioning. Monitor usage patterns and costs to balance performance and efficiency.

  3. Set capacity boundaries:

    • Minimum RCUs/WCUs: Maintains sufficient capacity during low-traffic periods.

    • Maximum RCUs/WCUs: Accommodates peak traffic demands and protects against runaway scaling events.

For predictable traffic patterns and planned events, Application Auto Scaling supports scheduled scaling actions for DynamoDB tables. These scheduled actions allow you to adjust the read or write capacity of your tables at predetermined times using cron expressions.

For guidance on configuring and managing DynamoDB Auto Scaling, see Managing throughput capacity automatically with DynamoDB Auto Scaling.

Note

Be aware that Auto Scaling has some latency and may not react quickly enough to sudden traffic spikes, which is why proper target utilization settings with adequate headroom are important.

Optimizing your table's or index's read or write Auto Scaling settings

Use this procedure when Auto Scaling is enabled but throttling still occurs. You can tune auto-scaling independently for both tables and global secondary indexes (GSIs), with separate controls for read and write capacity units.

  • Adjust target utilization: Consider lowering the target utilization for your table or GSIs to trigger scaling earlier before throttling occurs. Ensure that you monitor your traffic after making these adjustments. See Configuring table Auto Scaling to adjust the read or write capacity of your table or GSI for more information about capacity consumption and cost implications.

  • Review capacity boundaries: Ensure your minimum and maximum capacity settings align with your actual workload patterns.

  • Modify scaling policies: Modify your scaling policies to be more aggressive for workloads with rapid changes in demand.

Switching to on-demand capacity mode

For general information about switching capacity modes, see Considerations when switching capacity modes in DynamoDB. Refer to the Service Quotas to learn about specific constraints when switching mode.

Increasing GSI throughput capacity

Use this procedure when Auto Scaling is not enabled on your GSI or you need immediate capacity increase.

  1. Update the GSI's provisioned capacity using the DynamoDB console, Amazon CLI, or SDK:

    • For read capacity: Increase the ReadCapacityUnits parameter for the specific GSI, which specifies the maximum number of reads the GSI can consume per second before DynamoDB throttles requests. Note that GSIs only support eventually consistent reads.

    • For write capacity: Increase the WriteCapacityUnits parameter for the specific GSI, which specifies the maximum number of writes the GSI can consume per second before DynamoDB throttles requests.

  2. Ensure that the GSI's provisioned throughput capacity remains within the per-account and per-table throughput quotas.

Additional resources