Repository navigation
Description
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=trueWindows CMD, then start pwsh or powershell from the same window:
set AWS_NEW_RETRIES_2026=trueSet 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_2026Also 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.ReceiveMessageapply 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-afterresponse header. When a service sends it, the SDK waits at least its own computed backoff and at most 5 seconds longer. - Throttled requests in
adaptivemode now retry. Previously, a throttling error inadaptivemode 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 $ddbConfigFor 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
ashishdhingra commentedon Nov 11, 2026
Update: The updated retry behavior is now the default
Starting in
AWS.Tools.Commonversion5.0.332(released November 10, 2026), AWS Tools for PowerShell uses the updated retry behavior by default, and theAWS_NEW_RETRIES_2026environment 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
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 honorAWS_MAX_ATTEMPTSandmax_attempts. You can remove the variable after you upgrade.5.0.332or later. To test it first, update toAWS.Tools.Commonversion5.0.202or later and setAWS_NEW_RETRIES_2026=truein a non-production environment.AWS_NEW_RETRIES_2026=false? In5.0.332and later, the SDK ignores the variable, so it no longer keeps the previous behavior.Restoring previous behavior
This SDK doesn't support
legacyretry mode, so a full revert isn't available. You can override max attempts withMaxErrorRetryon-ClientConfig,AWS_MAX_ATTEMPTS, ormax_attemptsin 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.