Skip to content

Announcement: Updated default retry behavior (2026) #3416

Open

Description

@millems

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=true

The 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_2026

In 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 Functions GetActivityTask, and SWF PollForActivityTask and PollForDecisionTask 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 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-after response header. When a service sends it, the SDK waits at least its own computed backoff and at most 5 seconds longer.
  • StandardOptions.BaseDelay now takes effect. Previously, without the opt-in, the SDK ignored it.
  • Some retry options are deprecated. retry.DefaultRetryCost, retry.DefaultRetryTimeoutCost, StandardOptions.Timeouts, and StandardOptions.RetryTimeoutCost are deprecated. Setting Timeouts or RetryTimeoutCost has no effect, and retry.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

  1. pinned this issue on May 20, 2026
  2. vasilisnasopoulos commented on Oct 25, 2026

    @vasilisnasopoulos

    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.Standard from v1.47.4 (token bucket, costs, backoff), in the same order as aws/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.

    clients requests per client during the outage load on the service, 2026 transient old transient throttling (both)
    10 ~3,000 1.01x 1.03x 1.03x
    300 ~100 1.35x 2.00x 2.00x
    1,000 ~30 2.16x 2.87x 2.9x
    10,000 ~3 3.00x 2.86x 2.9x

    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-after as the fleet-level lever (same setup, 10,000 clients, 2026 mode). The SDK clamps the server value
    to [backoff, backoff + 5 s] (adjustForRetryAfterHeader, middleware.go:526-556):

    outage retry-after sent load on the service during the outage retries that land after the outage, per request
    30 s none 3.00x 0.00
    30 s 5 s 2.50x 0.33
    30 s 30 s 2.49x 0.34
    5 s none 2.98x 0.02
    5 s 5 s or 30 s 1.00x 1.00

    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:

    1. For fleets where each client sends only a few requests per incident, is the retry quota meant to help the service, or is
      x-amz-retry-after the intended mechanism there?
    2. Is the 5-second upper clamp on x-amz-retry-after a 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.

  3. pulimsr commented on Nov 11, 2026

    @pulimsr
    Collaborator

    Update: The updated retry behavior is now the default

    Starting in github.com/aws/aws-sdk-go-v2 version v1.48.0 and 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 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. 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-v2 version v1.42.0 and later.

    What this means for you

    • Already set 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 custom Backoff now receives the same attempt number as without the opt-in (one higher than under it), so remove any attempt+1 adjustment. HTTP 429 responses that don't match a modeled error are now retried as throttling errors.
    • Haven't opted in? You get the updated behavior when you upgrade github.com/aws/aws-sdk-go-v2 to v1.48.0 or later and your service modules to their November 10, 2026 releases or later. To test it first, update github.com/aws/aws-sdk-go-v2 to version v1.42.0 or later and your service modules to versions released on or after June 8, 2026. Then set AWS_NEW_RETRIES_2026=true in a non-production environment.
    • Set AWS_NEW_RETRIES_2026=false? In v1.48.0 and 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 standard mode defaults have been removed, and this SDK has no legacy retry mode. You can override max attempts, the backoff (retry.NewExponentialJitterBackoff restores 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.

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

Metadata

Metadata

Assignees

No one assigned

    Labels

    announcementThis is an announcement issue

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions

      ⌂ 换网址