UNAUTHENTICATED
GCP UNAUTHENTICATED means the request does not include valid authentication credentials for the requested Google Cloud API operation.
Last reviewed: April 15, 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 Unauthenticated Mean?
Google Cloud could not prove caller identity, so IAM authorization never begins. The useful tuple is credential source, token type, and whether the claims match the API and audience the workload is calling.
Common Causes
- -Access token, ID token, or signed credential is missing, expired, or malformed.
- -Token audience, issuer, or scope does not match the target API endpoint.
- -Application Default Credentials resolve from the wrong source for the running environment.
- -Workload Identity Federation or service-account impersonation is configured incorrectly.
- -Proxy, gateway, or middleware strips
Authorizationheaders in transit. - -Metadata server or token exchange path is unavailable during startup or refresh.
How to Fix Unauthenticated
- 1Inspect the active credential source and token type in runtime before rotating anything.
- 2Refresh or reacquire credentials using the correct ADC flow for that environment and target API.
- 3Verify target API scopes or audience plus the full impersonation or federation chain end to end.
- 4Trace request headers through ingress and proxy hops to ensure auth metadata is preserved.
Step-by-Step Diagnosis for Unauthenticated
- 1Capture the failing request with timestamp, endpoint, principal identity hint, and token type.
- 2Verify whether the target API expects an OAuth access token, an ID token for a service URL, or an impersonated service-account token.
- 3Compare token claims or token source against API expectations for audience, issuer, expiry, and scope.
- 4Verify ADC resolution order and identity source used by the workload at runtime.
- 5Check clock drift, metadata-server reachability, and token exchange logs to isolate environment-specific auth failures.
Seen in Production
- -GKE workload migrates to Workload Identity Federation, but one namespace is missing the principal mapping, so only that deployment starts returning UNAUTHENTICATED.
- -Client keeps minting an ID token for an old Cloud Run audience and reuses it against a different API hostname after migration.
- -Ingress strips
Authorizationon an internal redirect, so the origin service sees a request with no bearer token even though the client sent one.
ADC and Token-Type Validation
- -Confirm ADC is loading the intended credential file or metadata identity (example: local user ADC file is mounted into a production container unexpectedly).
- -Inspect token type and claims for endpoint compatibility (example: ID token minted for a Cloud Run URL is sent to a Google API that expects an OAuth access token).
Federation, Impersonation, and Transport Integrity
- -Audit Workload Identity Federation or impersonation steps for trust and principal mapping issues (example: pool provider subject mismatch blocks token exchange).
- -Trace auth headers across proxies and service mesh layers (example: ingress policy drops
Authorizationon internal redirect).
Decision Shortcut: Wrong Token Type vs Wrong Identity Source
- -If a manually minted access token works but the app path fails, suspect ADC source precedence or federation wiring before IAM roles.
- -If the same runtime succeeds only when you swap an ID token for an OAuth access token, treat it as endpoint-token mismatch rather than missing permissions.
Wrong Fix to Avoid
- -Do not add broader IAM roles when the platform has not authenticated the caller identity yet.
- -Do not swap between ID tokens and access tokens blindly; first prove what the target endpoint actually expects.
Implementation Examples
{
"error": {
"code": 401,
"message": "Request is missing valid authentication credentials.",
"status": "UNAUTHENTICATED"
}
}gcloud auth list
gcloud auth application-default print-access-token >/tmp/access.token
curl -i https://storage.googleapis.com/storage/v1/b \
-H "Authorization: Bearer $(cat /tmp/access.token)"SERVICE_URL=https://SERVICE-HASH-uc.a.run.app
gcloud auth application-default print-access-token >/tmp/access.token
gcloud auth print-identity-token --audiences="$SERVICE_URL" >/tmp/id.token
curl -i https://storage.googleapis.com/storage/v1/b \
-H "Authorization: Bearer $(cat /tmp/access.token)"
curl -i "$SERVICE_URL" \
-H "Authorization: Bearer $(cat /tmp/id.token)"Incident Timeline
13:01 UTC
A deploy changes the auth path without changing business logic
Signal: The workload moves from a key file, local ADC, or one federation chain to another, and only after that do requests start returning UNAUTHENTICATED.
Why it matters: That pattern points to identity acquisition drift first, not to permissions or application behavior.
13:04 UTC
The runtime sends the wrong credential shape for the target endpoint
Signal: An OAuth access token is expected but an ID token is sent, or the ID token audience still references the old Cloud Run URL.
Why it matters: Token type and audience mismatch is one of the fastest ways to create a 401/UNAUTHENTICATED wall after migrations.
13:07 UTC
An intermediate hop can also erase otherwise valid auth
Signal: The client or pod has a valid token, but the edge or proxy path strips Authorization during a rewrite or redirect.
Why it matters: If direct origin tests work and edge path tests fail, the auth bug lives in transport, not in the token minting code.
13:15 UTC
The right ADC path and token contract are replayed successfully
Signal: The same runtime starts minting the correct token type or restores the header intact, and the exact request stops returning UNAUTHENTICATED.
Why it matters: That confirms the fix belongs in credential acquisition or transport preservation, not in IAM role expansion.
Seen in Production
Service moved from key file auth to workload identity without full trust mapping
Frequency: common
Example: Pods start returning UNAUTHENTICATED after deployment despite unchanged business logic.
Fix: Correct pool/provider subject mapping and revalidate token exchange path.
Token audience mismatch after endpoint migration
Frequency: common
Example: Client keeps minting tokens for old service audience after API hostname change.
Fix: Update token minting audience and redeploy clients with validated claim checks.
Proxy drops Authorization during redirect or internal rewrite
Frequency: medium
Example: Client sends a valid bearer token to the edge, but the origin receives no auth header after gateway normalization.
Fix: Preserve auth headers across internal rewrites and add synthetic auth probes through the full edge path.
Metadata server is reachable only intermittently during cold start
Frequency: medium
Example: New pods fail the first token fetch and return UNAUTHENTICATED for a short window before retries warm the identity path.
Fix: Add startup auth readiness checks and monitor metadata or federation token exchange latency during scale events.
Wrong Fix vs Better Fix
Grant IAM roles vs fix caller authentication
Wrong fix: Add broader project or service IAM roles because the API rejected the request.
Better fix: Treat UNAUTHENTICATED as an identity proof failure first and fix ADC source, token type, audience, or transport preservation before reviewing IAM.
Why this is better: Authorization never begins until Google accepts the caller identity. Permission changes do not solve missing or invalid credentials.
Swap token types blindly vs prove endpoint expectations
Wrong fix: Try ID tokens, access tokens, and random scopes until something eventually works.
Better fix: Prove whether the endpoint expects an OAuth access token, a service audience-bound ID token, or an impersonated credential path, then mint exactly that contract.
Why this is better: Random token swapping can mask the real issue briefly but leaves the system brittle and hard to reason about after the next migration.
Validate locally only vs replay in the failing runtime path
Wrong fix: Confirm the call works from a developer shell and assume the pod, job, or proxy path is fine.
Better fix: Re-run the exact request from the same runtime and through the same ingress path that originally failed, including header propagation.
Why this is better: Most UNAUTHENTICATED incidents are environment-specific. The production path must be proven, not inferred from a local test.
Debugging Tools
- -gcloud auth application-default diagnostics
- -gcloud auth list / print-access-token checks
- -JWT/OAuth claim inspection tools
- -Cloud Audit Logs authentication failures
- -Metadata-server and token-exchange diagnostics
- -Service mesh or proxy header tracing
How to Verify the Fix
- -Replay the exact failing request and confirm UNAUTHENTICATED is no longer returned.
- -Verify tokens refresh correctly across at least one full credential lifetime window.
- -Check logs for sustained absence of credential-validation failures after rollout.
- -Confirm the intended credential source remains stable across pod restarts, deploys, and token refresh events.
How to Prevent Recurrence
- -Standardize credential acquisition through shared auth libraries and environment-specific ADC policy.
- -Monitor token-expiry skew, metadata-server reachability, and impersonation error rates.
- -Add pre-deploy auth smoke tests that validate audience and scope against critical APIs.
Pro Tip
- -log hashed token claim fingerprints (
iss/aud/sub) at auth boundaries to detect silent credential-source drift before outages.
Decision Support
Official References
Provider Context
This guidance is specific to GCP services. Always validate implementation details against official provider documentation before deploying to production.