In May 2026, we announced an opt-in for updated retry behavior for the AWS SDKs, AWS Command Line Interface (AWS CLI), and AWS Tools for PowerShell.

Starting November 10, 2026, the updated behavior is the default, and we have removed the opt-in. Availability varies by SDK and tool. See the SDK availability and GitHub issues section for more details.

This post covers what changed, how to tell if you’re affected, and how to preserve the previous behavior.

SDK availability and GitHub issues

Every SDK and tool listed below, except Kotlin and Java, makes the updated behavior the default.

SDK Default in GitHub tracking issue
Java 2.x  To be announced. Tracking issue
Python (Boto3) botocore 1.44.0 Tracking issue
.NET AWSSDK.Core 4.0.103.0 Tracking issue
PowerShell AWS.Tools.Common, AWSPowerShell.NetCore, and AWSPowerShell 5.0.332 Tracking issue
JavaScript 3.x 3.1166.0, with @smithy/core 3.40.0 or later Tracking issue
PHP 3.403.3 Tracking issue
Kotlin  To be announced. To test now, opt in with 1.9.0 or later. Tracking issue
Rust aws-config 1.13.2, with BehaviorVersion::v2026_11_10() or later Tracking issue
Swift 1.8.24 Tracking issue
Ruby aws-sdk-core 3.267.0 Tracking issue
Go 2.x v1.48.0 Tracking issue
C++ 1.11.926 Tracking issue
AWS CLI 2.40.0 Tracking issue

Each tracking issue includes before-and-after defaults, code examples for overriding individual settings, and revert instructions for that SDK.

What’s changed

This update changes how standard and adaptive (a rate-limiting mode built on standard) retry modes handle failed requests. It also makes standard the default for SDKs that had previously defaulted to legacy.

Most SDKs already used the standard retry mode by default. It includes a retry quota, exponential backoff with jitter, and a standard set of retryable errors. The AWS SDKs for Python, Ruby, PHP, and Swift defaulted to legacy mode, which behaves inconsistently across SDKs. To compare retry modes across SDKs, see the Retry behavior documentation.

Most of these changes were available with the opt-in, and Announcing updated retry behavior for AWS SDKs and tools describes them in detail.

In summary:

  • Faster retries for transient errors. Transient errors (connection resets, HTTP 500/502/503/504) use a 50 ms base delay, and throttling errors use a 1,000 ms base delay. Previously, base delays varied across SDKs.
  • Retry quota updates. Each transient error retry costs 14 tokens (previously 5 or 10, depending on the SDK and the error), and each throttling retry costs 5 tokens, so the quota engages sooner during sustained outages. If you were using legacy mode, your SDK may not have had a standardized retry quota before. For details, see Retry quota (token bucket).
  • Amazon DynamoDB tuning. Amazon DynamoDB and Amazon DynamoDB Streams use a 25 ms base delay and 4 max attempts. Previous defaults varied by SDK (as many as 12 max attempts in some SDKs). For details, see DynamoDB in the retry behavior documentation.
  • Long-polling operations. When the retry quota is depleted, long-polling operations, such as Amazon Simple Queue Service (AWS SQS) ReceiveMessage operation, apply a backoff delay before returning an error. For more information, see the Long-polling operations documentation.

What’s new since May

  • The opt-in flag is removed. These releases stop reading AWS_NEW_RETRIES_2026, and setting the variable now has no effect. This change applies only to the versions listed in this post and later. Earlier versions still honor AWS_NEW_RETRIES_2026.
  • Minor SDK-specific changes. Some SDKs include other minor changes that weren’t part of the opt-in. Your SDK’s GitHub tracking issue lists them.

Does this impact me?

This update changes behavior within standard and adaptive retry modes. Whether you’re affected depends on your current configuration. For SDK-specific details, see the tracking issues in the SDK availability table. Generally:

  • No explicit retry configuration at all? You see all the changes when you upgrade. For SDKs that previously defaulted to legacy mode, this also switches the default to standard.
  • Explicitly set retry mode to standard or adaptive? You see the new backoff timing, retry quota costs, and DynamoDB defaults. Your mode choice doesn’t change, but how these modes behave does.
  • Explicitly set max_attempts or backoff settings? Those specific values stay as you configured them. Other settings you didn’t override, such as retry quota costs, update to the new defaults.
  • Explicitly set retry mode to legacy? What changes for legacy mode varies by SDK, and some SDKs don’t support it.
  • Already set AWS_NEW_RETRIES_2026=true? Most of your retry behavior stays the same when you upgrade. The minor SDK-specific changes that weren’t part of the opt-in still apply. You can remove the variable afterward.
  • Set AWS_NEW_RETRIES_2026=false? After you upgrade, the SDK ignores it and uses the updated behavior.

What to do when you upgrade

  1. Test the new version first. Upgrade to the version listed for your SDK in the SDK availability table, and run your workload in a non-production environment.
  2. Set any previous values you depend on. If your workload relies on a previous default, such as a higher max attempt count, set that value explicitly where your SDK supports it. DynamoDB clients have their own defaults, so check your SDK’s GitHub tracking issue for how to set them.
  3. Clean up AWS_NEW_RETRIES_2026 after you upgrade. Leaving it set doesn’t cause problems, but it no longer does anything.

Where you might notice a difference

For most workloads, the update is invisible or an improvement. Transient errors recover faster and you don’t need to change any code. The May announcement describes what to watch for. In summary:

  • Max attempts may have decreased. Some SDKs previously defaulted to more than 3 max attempts. If your workload relied on a high retry count, you may see more errors. You can override max_attempts to restore your previous value.
  • Some SDKs gain a retry quota for the first time. Some SDKs that defaulted to legacy mode had no standardized retry quota. They now stop retrying during sustained failures, so your application sees errors sooner during prolonged outages, but frees up threads and connections.
  • The retry quota activates sooner for transient errors, such as a wave of 500 responses.

For SDK-specific before and after values, see your SDK’s GitHub tracking issue in the SDK availability table.

How to preserve previous behavior

A complete revert is not available in every SDK. After you upgrade, unsetting AWS_NEW_RETRIES_2026 or setting it to false doesn’t restore the previous behavior.

Option 1: Set legacy mode

In SDKs that support legacy mode, you can set the retry mode to legacy to return to the previous default mode:

export AWS_RETRY_MODE=legacy

You can also set retry_mode = legacy in your shared AWS config file (~/.aws/config), or set the retry mode in code. The amount of previous behavior that legacy mode restores varies by SDK.

Important: Some SDKs and tools don’t accept legacy. Depending on the SDK or tool, a legacy setting causes an error when the configuration loads, or causes the entire config profile to be ignored, including credentials and Region. If several SDKs or tools share an environment or config file, set the retry mode in code or in a profile that only that application uses.

Option 2: Override specific values

In SDKs that don’t support legacy mode, or if you depend on only a few previous values, restore those values instead, such as max attempts:

export AWS_MAX_ATTEMPTS=5

Which settings you can override, and how, varies by SDK. Some SDKs offer a single setting that restores the previous behavior. Your SDK’s GitHub tracking issue lists the options, with code examples.

If you need to restore a previous value that your SDK doesn’t let you configure, tell us on your SDK’s GitHub tracking issue.

Conclusion

This update brings consistent, faster retry behavior across the AWS SDKs, and as of November 10, 2026, it’s the default for most SDKs. Test the new version on a non-production workload first, then roll it out to production. If you depend on a previous default, see the How to preserve previous behavior section earlier in this post.

Give us feedback

If you run into unexpected behavior, or if the changes work well for you, comment on your SDK’s GitHub tracking issue.

Learn more