TokenRefreshRequired
AWS TokenRefreshRequired means the temporary token in the request must be refreshed before Amazon S3 will accept the operation. In Amazon S3, this error returns HTTP 400.
Last reviewed: March 23, 2026|Source-backed guidance under our editorial policy
Start Here
Use the closest compare guide, playbook, or adjacent error page to narrow the decision faster before you start changing production systems.
This page is part of the Error Reference library. Learn more about the project or report a correction.
What Does Token Refresh Required Mean?
S3 recognizes that the request is using a refreshable temporary security context, but the token attached to the request is no longer acceptable in its current form. Unlike ExpiredToken, which is a hard end-of-life condition, TokenRefreshRequired indicates the client should obtain a fresh token set and resend the request before normal access resumes.
Common Causes
- -Application caches temporary credentials and keeps signing requests after the token should have been rotated.
- -Custom credential refresh logic exists but does not run before the next S3 request is signed.
- -Long-running workers or warm runtimes reuse STS credentials across jobs without checking freshness.
- -Temporary credentials are serialized to disk, env vars, or sidecar cache and reused after the original session should have been replaced.
How to Fix Token Refresh Required
- 1Refresh the temporary credentials from the underlying role/session provider and retry the request with the new token.
- 2Switch to SDK-managed refreshing providers instead of storing raw access key, secret key, and session token triples.
- 3Reduce token reuse windows by refreshing before expiry rather than waiting for request failure.
- 4Restart long-lived workers only as a fallback when the runtime has no safe credential refresh path.
Step-by-Step Diagnosis for Token Refresh Required
- 1Identify the credential source: STS AssumeRole, ECS task role, EC2 instance profile, web identity, or custom broker.
- 2Compare request failure time with the credential issue and expiration timestamps from the provider that minted the session.
- 3Inspect application logs to see whether a refresh attempt happened before the failing S3 call.
- 4Verify the process is not reusing stale credentials from env vars, mounted files, or in-memory singleton caches.
Refresh Lifecycle Audit
- -Trace how temporary credentials are acquired, cached, refreshed, and injected into S3 clients (example: a worker stores AssumeRole output once at startup and never refreshes it).
- -Compare token refresh threshold with actual job duration (example: 60-minute session is reused by a 3-hour migration process without mid-run rotation).
Provider and Runtime Drift Checks
- -Inspect whether multiple credential sources compete and reintroduce stale values (example: fresh task-role creds exist, but env vars override them with an older session token).
- -Audit warm-runtime behavior in Lambda, containers, or daemonized workers (example: one warm container keeps an S3 client alive long after its original token should have been rotated).
Implementation Examples
import { fromTemporaryCredentials } from "@aws-sdk/credential-providers";
import { S3Client } from "@aws-sdk/client-s3";
const credentials = fromTemporaryCredentials({
params: { RoleArn: "arn:aws:iam::123456789012:role/WorkerRole" },
});
const s3 = new S3Client({ credentials });aws sts assume-role \
--role-arn arn:aws:iam::123456789012:role/WorkerRole \
--role-session-name refresh-debug \
--query 'Credentials.Expiration' \
--output textSeen in Production
Long-running upload worker keeps stale session token in memory
Frequency: medium
Example: A batch uploader starts with temporary credentials, runs for hours, and eventually receives TokenRefreshRequired because the S3 client never rotated the session.
Fix: Use a refreshing provider and rebuild or refresh the client credentials before the next upload chunk is signed.
Debugging Tools
- -AWS SDK credential-provider debug logs
- -STS AssumeRole/GetSessionToken audit trail
- -CloudTrail event history for session refresh patterns
- -Credential expiry telemetry
How to Verify the Fix
- -Replay the same S3 call after credential refresh and confirm TokenRefreshRequired no longer appears.
- -Validate the new credential set has a future expiration timestamp and maps to the expected principal/account.
- -Monitor long-running jobs and confirm they continue successfully past the previous failure window.
How to Prevent Recurrence
- -Use SDK credential providers that support automatic refresh instead of persisting raw STS outputs in application code.
- -Set a refresh buffer before expiry so credentials rotate safely ahead of the next signed S3 request.
- -Centralize temporary-credential management and block direct token caching in shared libraries.
Pro Tip
- -log credential source and expiry metadata in debug mode so refresh regressions can be traced without ever printing the actual secret values.
Official References
Provider Context
This guidance is specific to AWS services. Always validate implementation details against official provider documentation before deploying to production.