Skip to content

Announcement: Updated default retry behavior (2026) #418

Open

Description

@millems

Important

Update: Starting in AWS.Tools.Common version 5.0.332 (released November 10, 2026), the updated retry behavior is the default and the AWS_NEW_RETRIES_2026 environment variable is removed. This applies to all editions: AWS.Tools, AWSPowerShell.NetCore, and AWSPowerShell. To test the updated behavior before you upgrade, see How to opt in early. To keep some previous settings after you upgrade, such as max attempts, see How to revert.

This issue tracks the 2026 retry updates for AWS Tools for PowerShell. See the announcement blog post for the full story across all AWS SDKs, including how to tell if you are affected.

Status

Opt-in available in AWS.Tools.Common version 5.0.202 and later
Opt-in flag AWS_NEW_RETRIES_2026=true (removed in version 5.0.332)
Default in AWS.Tools.Common version 5.0.332 and later (released November 10, 2026)

What changed

Starting in version 5.0.332 (or earlier, if you set AWS_NEW_RETRIES_2026=true), the retry defaults within standard and adaptive modes update. The retry mode itself does not change. Every AWS.Tools.<Service> module requires the matching AWS.Tools.Common version, so updating any service module to 5.0.332 brings the new default with it.

If you have explicitly configured max attempts (MaxErrorRetry on -ClientConfig, the AWS_MAX_ATTEMPTS environment variable, or max_attempts in the shared config file's [default] profile or the profile named by AWS_PROFILE), your value takes precedence. This now includes DynamoDB and DynamoDB Streams. -ProfileName and Set-AWSCredential choose credentials only. To apply max_attempts from a named profile, also set AWS_PROFILE to that profile name before you start the session.

Setting Before After
Transient (non-throttling) base delay 1,000 ms 50 ms
Throttling base delay 1,000 ms 1,000 ms (unchanged)
Max attempts 3 3 (unchanged)
Transient retry quota cost 5 tokens 14 tokens
DynamoDB and DynamoDB Streams
Transient (non-throttling) base delay 1,000 ms 25 ms
Throttling base delay 1,000 ms 1,000 ms (unchanged)
Max attempts 11 4

DynamoDB defaults use a shorter base delay to match its low-latency profile. The additional attempt keeps the last retry's maximum backoff comparable to the general default.

Transient errors (such as 500s and connection resets) now use a much shorter backoff than throttling errors (where the service asks you to slow down). Connection resets are first retried immediately (up to 10 times) before backoff applies. For details on backoff timing, error classification, and the retry quota, see Retry behavior in the AWS SDKs. For retry mode selection and configuration options, see Retry behavior in the AWS SDKs.

How to opt in early

Update to AWS.Tools.Common version 5.0.202 or later, then set the environment variable:

$env:AWS_NEW_RETRIES_2026 = "true"

Bash:

export AWS_NEW_RETRIES_2026=true

Windows CMD, then start pwsh or powershell from the same window:

set AWS_NEW_RETRIES_2026=true

Set the variable before you run the first AWS cmdlet in a session. The module reads it once per session.

The opt-in doesn't include two changes that ship with 5.0.332: retries of HTTP 429 responses without a recognized error code, and DynamoDB cmdlets honoring AWS_MAX_ATTEMPTS and max_attempts.

In version 5.0.332 and later, the updated behavior is the default and the SDK ignores AWS_NEW_RETRIES_2026. You can remove it from your configuration after you upgrade.

How to revert

In versions earlier than 5.0.332, remove the environment variable:

Remove-Item Env:AWS_NEW_RETRIES_2026

Also remove it wherever you set it (your PowerShell profile, or a user or system environment variable), then start a new PowerShell session.

In version 5.0.332 and later, the updated behavior is the default and the SDK ignores AWS_NEW_RETRIES_2026, so unsetting it or setting it to false doesn't restore the previous behavior. The updated behavior cannot be reverted because this SDK does not support legacy retry mode. Don't set retry_mode = legacy in your shared config file: the SDK rejects that profile entirely, so cmdlets that use it fail with a credentials or region error. You can still override max attempts: set MaxErrorRetry on a -ClientConfig object (it counts retries, so attempts = value + 1), or set AWS_MAX_ATTEMPTS or max_attempts (these count attempts). This includes DynamoDB cmdlets, as shown in Overriding specific settings.

If this is a concern for your use case, please let us know in this issue.

Where you might notice a difference

Transient errors recover faster because the base delay is significantly shorter.

  • Retry quota activates sooner for transient errors. Each transient retry costs 14 tokens (previously 5 for most errors). During sustained transient failures (such as 500s and connection resets), the retry quota triggers at a lower failure rate than the previous version of standard mode. Throttling retries cost 5 tokens. A retried call that succeeds now returns its retry cost to the quota.
  • Long-polling operations now back off when the retry quota is depleted. Operations like SQS.ReceiveMessage apply a backoff delay before returning an error, even when retries are blocked. Without this, a polling loop would send its next request immediately after each error, spiking client CPU usage and generating additional traffic. For details, see long-polling operations.
  • More HTTP 429 responses are retried. An HTTP 429 response without a recognized error code is now retried as a throttling error.
  • The SDK honors the x-amz-retry-after response header. When a service sends it, the SDK waits at least its own computed backoff and at most 5 seconds longer.
  • Throttled requests in adaptive mode now retry. Previously, a throttling error in adaptive mode could fail after the first attempt because the client-side rate limiter didn't refill while waiting.

Overriding specific settings

If you want to keep the previous max attempts, set it explicitly. Backoff timing and token costs can't be set individually. You can turn off the retry quota for a cmdlet with a -ClientConfig whose ThrottleRetries is $false. Precedence applies per setting.

For example, to use the new backoff timing but keep a higher DynamoDB max attempts:

Import-Module AWS.Tools.DynamoDBv2  # or AWSPowerShell.NetCore

$ddbConfig = New-Object -TypeName Amazon.DynamoDBv2.AmazonDynamoDBConfig
$ddbConfig.MaxErrorRetry = 10  # 10 retries = 11 attempts, the previous default

Get-DDBTable -TableName <TABLE_NAME> -ClientConfig $ddbConfig

For the full list of configurable settings and their precedence, see Retry behavior in the AWS SDKs.

Feedback

If you encounter unexpected behavior or have questions, comment on this issue. If you need a previous value that you can't configure, let us know here.

Activity

  1. pinned this issue on May 20, 2026
  2. ashishdhingra commented on Nov 11, 2026

    @ashishdhingra
    Contributor

    Update: The updated retry behavior is now the default

    Starting in AWS.Tools.Common version 5.0.332 (released November 10, 2026), AWS Tools for PowerShell uses the updated retry behavior by default, and the AWS_NEW_RETRIES_2026 environment variable is removed. This applies to all editions: AWS.Tools, AWSPowerShell.NetCore, and AWSPowerShell. For the announcement across all AWS SDKs, see Updated retry behavior is now the default for AWS SDKs and tools.

    What this means for you

    • Already set AWS_NEW_RETRIES_2026=true? Backoff, retry quota costs, and DynamoDB defaults stay the same. Two things change: HTTP 429 responses without a recognized error code are now retried as throttling errors, and DynamoDB cmdlets now honor AWS_MAX_ATTEMPTS and max_attempts. You can remove the variable after you upgrade.
    • Haven't opted in? You get the updated behavior when you upgrade to 5.0.332 or later. To test it first, update to AWS.Tools.Common version 5.0.202 or later and set AWS_NEW_RETRIES_2026=true in a non-production environment.
    • Set AWS_NEW_RETRIES_2026=false? In 5.0.332 and later, the SDK ignores the variable, so it no longer keeps the previous behavior.

    Restoring previous behavior

    This SDK doesn't support legacy retry mode, so a full revert isn't available. You can override max attempts with MaxErrorRetry on -ClientConfig, AWS_MAX_ATTEMPTS, or max_attempts in the shared config file, for DynamoDB cmdlets too. See How to revert in the description for details. If you need a previous value that you can't configure, let us know here.

    We've updated the description with the new version information and revert instructions, and corrected some of the before-and-after values. If you run into unexpected behavior, comment here.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions

      ⌂ 换网址