Repository navigation
Description
Important
Update: Starting in github.com/aws/aws-sdk-go-v2 version v1.48.0 and the service module releases of November 10, 2026, the updated retry behavior is the default and the SDK no longer reads the AWS_NEW_RETRIES_2026 environment variable. Update your service modules too: earlier releases of service/dynamodb, service/dynamodbstreams, service/sqs, service/sfn, and service/swf still read the variable. To test the updated behavior before you upgrade, see How to opt in early. To restore previous behavior after you upgrade, see How to revert.
This issue tracks the 2026 retry updates for AWS SDK for Go 2.x. 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 | github.com/aws/aws-sdk-go-v2 version v1.42.0 and later |
| Opt-in flag | AWS_NEW_RETRIES_2026=true (removed in version v1.48.0) |
| Default in | github.com/aws/aws-sdk-go-v2 version v1.48.0 and later, with service modules released on or after November 10, 2026 |
What changed
Starting in version v1.48.0 (or earlier, if you set AWS_NEW_RETRIES_2026=true), the retry defaults within the standard and adaptive modes update. Your retry mode itself does not change.
If you have explicitly configured max attempts or backoff, your value takes precedence for that setting. A custom Backoff receives the same attempt number as before (1 for the first retry). If you wrote a Backoff for the opt-in on an earlier version, where it received one lower, remove any attempt+1 adjustment when you upgrade, or its delays double. An x-amz-retry-after response header can also lengthen the wait. A custom retryer replaces the DynamoDB defaults. If you set it with config.WithRetryer, the SDK also stops reading AWS_MAX_ATTEMPTS. If you set it per client with o.Retryer, AWS_MAX_ATTEMPTS still applies.
| Setting | Before | After |
|---|---|---|
| Transient (non-throttling) base delay | 1,000 ms | 50 ms |
| Throttling base delay | 1,000 ms | 1,000 ms |
| Max attempts | 3 | 3 (unchanged) |
| Transient retry quota cost | 5 tokens (10 for timeouts) | 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 |
| Max attempts | 3 | 4 |
DynamoDB defaults use a shorter base delay to match its low-latency profile. For transient errors, the additional attempt keeps the last retry's maximum backoff the same as the general default.
The backoff now starts at 1 times the base delay instead of 2 times. Previously, the first retry waited up to 2 seconds after any error. Now it waits up to 50 ms after a transient error (25 ms for DynamoDB) and up to 1 second after a throttling error.
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). 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 github.com/aws/aws-sdk-go-v2 to version v1.42.0 or later (run go get github.com/aws/aws-sdk-go-v2@latest explicitly, because updating a service module raises the root module only to the minimum version that service module requires), and update your service modules to versions released on or after June 8, 2026 (for example, service/dynamodb v1.59.0 and service/sqs v1.44.0). Then set the environment variable. Only the exact value true enables the opt-in:
export AWS_NEW_RETRIES_2026=trueThe opt-in previews the new defaults: delays, attempts, token costs, long-polling backoff, and x-amz-retry-after handling. It doesn't preview two changes in v1.48.0: retries of HTTP 429 responses that don't match a modeled error, and the attempt number that a custom Backoff receives.
In version v1.48.0 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 v1.48.0, remove the environment variable:
unset AWS_NEW_RETRIES_2026In version v1.48.0 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. A full revert isn't available: the previous standard mode defaults have been removed, and this SDK has no legacy retry mode. Setting AWS_RETRY_MODE=legacy or retry_mode = legacy makes configuration loading fail with unknown RetryMode, legacy. You can override some individual settings:
| Setting | Can revert? | How |
|---|---|---|
| Max attempts | Yes | Set AWS_MAX_ATTEMPTS or configure in code. |
| Base backoff delay | Yes | Set StandardOptions.BaseDelay = 2*time.Second to match the previous timing (non-throttling errors only). |
| Per-error-type backoff split | Yes | Supply a custom Backoff, as shown below. |
| Retry quota token costs | Partly | Set RetryCost and ThrottlingRetryCost. The previous 10-token cost for timeouts can't be restored. |
| Long-polling backoff on depleted quota | Partly | No setting. In v1.48.0 and later, you can remove the SetLongPollingContext initialize middleware with an APIOptions function (stack.Initialize.Remove("SetLongPollingContext")). On earlier versions, that call returns a not-found error that fails the operation. |
import (
"context"
"time"
"github.com/aws/aws-sdk-go-v2/aws/retry"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/dynamodb"
)
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
// handle error
}
client := dynamodb.NewFromConfig(cfg, func(o *dynamodb.Options) {
o.Retryer = retry.NewStandard(func(so *retry.StandardOptions) {
so.MaxAttempts = 3
so.RetryCost = 5
so.ThrottlingRetryCost = 5
// The previous backoff: full jitter, up to 2 seconds on the first
// retry for any error, doubling up to 20 seconds.
so.Backoff = retry.NewExponentialJitterBackoff(20 * time.Second)
})
})This restores the previous backoff timing, max attempts (unless AWS_MAX_ATTEMPTS or RetryMaxAttempts is set, which takes precedence), and token costs, except the 10-token timeout cost. It doesn't restore the 1-token increment after a successful retry, and HTTP 429 responses that don't match a modeled error are still retried. Long-polling backoff and x-amz-retry-after handling still apply.
If full revert 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, or 10 for timeouts). 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.
- Long-polling operations now back off when the retry quota is depleted. SQS
ReceiveMessage, Step FunctionsGetActivityTask, and SWFPollForActivityTaskandPollForDecisionTaskapply 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 that doesn't match a modeled error is now retried as a throttling error. The endpoint credentials provider also treats HTTP 429 as throttling.
- 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. StandardOptions.BaseDelaynow takes effect. Previously, without the opt-in, the SDK ignored it.- Some retry options are deprecated.
retry.DefaultRetryCost,retry.DefaultRetryTimeoutCost,StandardOptions.Timeouts, andStandardOptions.RetryTimeoutCostare deprecated. SettingTimeoutsorRetryTimeoutCosthas no effect, andretry.DefaultRetryCost(5) is no longer the default cost (14).
Overriding specific settings
You do not have to accept all changes as a bundle. Some changes can't be reverted: x-amz-retry-after handling, retries of HTTP 429 responses that don't match a modeled error, the single retry cost for timeouts, and the 1-token success increment (NoRetryIncrement), which the SDK now adds only when the first attempt succeeds. Previously, a successful retry also added it. A successful retry still refunds its retry cost. If you want to keep a specific previous value, set it explicitly. Precedence applies per setting for max attempts.
A backoff override replaces the whole new backoff. For example, retry.AddWithMaxBackoffDelay uses the previous formula (up to 2 seconds on the first retry for any error), which also drops DynamoDB's 25 ms base delay.
For example, to use the new backoff timing but keep a higher DynamoDB max attempts:
import (
"context"
"github.com/aws/aws-sdk-go-v2/config"
"github.com/aws/aws-sdk-go-v2/service/dynamodb"
)
cfg, err := config.LoadDefaultConfig(context.TODO())
if err != nil {
// handle error
}
client := dynamodb.NewFromConfig(cfg, func(o *dynamodb.Options) {
o.RetryMaxAttempts = 9
})To set max attempts for every client, use config.WithRetryMaxAttempts(9). Don't use config.WithRetryer for this: it replaces DynamoDB's 25 ms default and stops AWS_MAX_ATTEMPTS from being read.
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
vasilisnasopoulos commentedon Oct 25, 2026
Thanks for opening the opt-in window. One question about how the retry quota behaves in large fleets of low-volume clients
(Lambda, containers), measured against the 2026 defaults.
I drove the real
retry.Standardfrom v1.47.4 (token bucket, costs, backoff), in the same order asaws/retry/middleware.go,in a simulation: 1,000 req/s total, spread over N clients, 30-second full outage (every attempt fails), one SDK client per caller.
With a 50% failure rate instead of 100%, the quota blocked no retries at all from about 600 clients up, in both modes (~1.75x).
So the quota only engages for a client that sends roughly 30+ (transient) or 100+ (throttling) requests within the incident. The 2026
change moves that point by about 3x for transient errors and leaves throttling where it was. This matches the documented scope
("a single SDK client instance … not shared across processes or hosts"), so I'm not reporting a bug.
I then looked at
x-amz-retry-afteras the fleet-level lever (same setup, 10,000 clients, 2026 mode). The SDK clamps the server valueto [backoff, backoff + 5 s] (
adjustForRetryAfterHeader,middleware.go:526-556):For a 30-second outage, the service can bring the fleet down from about 3x to about 2.5x, whatever value it sends, because of the 5-second cap.
For a short outage it works well during the outage, but every deferred retry lands in the first few seconds after recovery.
Two questions:
x-amz-retry-afterthe intended mechanism there?x-amz-retry-aftera deliberate bound (latency?), and is it expected to be enough for longer incidents?Limits: failures are random and independent of load (no overload feedback); one seed; DynamoDB's 4-attempt profile not modelled.
pulimsr commentedon Nov 11, 2026
Update: The updated retry behavior is now the default
Starting in
github.com/aws/aws-sdk-go-v2versionv1.48.0and the service module releases of November 10, 2026, the AWS SDK for Go 2.x uses the updated retry behavior by default, and the SDK no longer reads theAWS_NEW_RETRIES_2026environment variable. Update your service modules too: earlier releases ofservice/dynamodb,service/dynamodbstreams,service/sqs,service/sfn, andservice/swfstill read the variable. For the announcement across all AWS SDKs, see Updated retry behavior is now the default for AWS SDKs and tools.The opt-in is available in
github.com/aws/aws-sdk-go-v2versionv1.42.0and later.What this means for you
AWS_NEW_RETRIES_2026=true? The retry defaults stay the same when you upgrade, and you can remove the variable afterward. Two things differ from the opt-in. A customBackoffnow receives the same attempt number as without the opt-in (one higher than under it), so remove anyattempt+1adjustment. HTTP 429 responses that don't match a modeled error are now retried as throttling errors.github.com/aws/aws-sdk-go-v2tov1.48.0or later and your service modules to their November 10, 2026 releases or later. To test it first, updategithub.com/aws/aws-sdk-go-v2to versionv1.42.0or later and your service modules to versions released on or after June 8, 2026. Then setAWS_NEW_RETRIES_2026=truein a non-production environment.AWS_NEW_RETRIES_2026=false? Inv1.48.0and later, the SDK ignores the variable, so it no longer keeps the previous behavior.Restoring previous behavior
A full revert isn't available: the previous
standardmode defaults have been removed, and this SDK has nolegacyretry mode. You can override max attempts, the backoff (retry.NewExponentialJitterBackoffrestores the previous timing), and retry quota costs, except the 10-token timeout cost. A custom retryer replaces the DynamoDB defaults. 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.