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|Editorial standard: source-backed technical guidance
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 textHow 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.
Decision Support
Compare Guide
HTTP 400 vs 422: Bad Request vs Unprocessable Content
Fix API payload issues faster by using 400 for malformed syntax and 422 for semantic validation failures, so clients correct format before business rules.
Playbook
CORS Error Fix Playbook (Preflight / Origin / Credentials)
Use this playbook to separate browser-enforced cross-origin policy failures from server-side CORS header and route defects and apply strict origin and credential controls safely.
Playbook
Validation Failure Playbook (400 / 422 / INVALID_ARGUMENT)
Use this playbook to separate malformed-request failures from semantic validation failures, then fix request contracts without broad server-side bypasses.
Official References
Provider Context
This guidance is specific to AWS services. Always validate implementation details against official provider documentation before deploying to production.