UNKNOWN
GCP UNKNOWN means the RPC failed with unclassified error context that did not map to a more specific canonical code.
Last reviewed: February 17, 2026|Editorial standard: source-backed technical guidance
What Does Unknown Mean?
At the gRPC protocol level, UNKNOWN (code 2) means the runtime cannot classify the failure into a known local status code. INTERNAL (code 13) signals an origin service invariant failure, while UNKNOWN signals translation loss or missing error detail across boundaries.
Common Causes
- -A status from another address space could not map cleanly to known local error semantics.
- -A gateway, proxy, or interceptor stripped structured error details before response translation.
- -An unhandled server exception terminated execution without explicit status mapping.
- -REST-gRPC translation layers collapsed a specific backend failure into a generic unknown code.
How to Fix Unknown
- 1Capture request ID, trace ID, region, method, and raw status payload from the failing path.
- 2Correlate client, gateway, and backend logs for the same correlation identifiers.
- 3Treat UNKNOWN as ambiguous and retry only idempotent calls when duplicate side effects cannot occur. Stop retries on write paths or any flow with data-loss risk, then escalate with correlation evidence.
- 4Escalate repeatable same-input failures with a support-ready evidence bundle.
Step-by-Step Diagnosis for Unknown
- 1Collect raw code, message, details, and transport-level metadata from the failing call.
- 2Compare direct service responses against gateway-translated responses to isolate mapping loss.
- 3Correlate failure windows with deployment events, proxy config changes, and dependency incidents.
- 4Reproduce with one minimal request and verify whether error classification remains UNKNOWN.
Translation Boundary Analysis
- -Trace where specific errors collapse into UNKNOWN across hops (example: backend returns INTERNAL but edge layer emits UNKNOWN after response translation).
- -Inspect middleware and gateway error mappers for dropped
google.rpc.Statusdetails (example: detailAnypayload removed by a custom interceptor).
UNKNOWN vs INTERNAL
- -Differentiate propagation paths: UNKNOWN often appears when INTERNAL cannot propagate through gateway or transport translation.
- -Differentiate fault locus: UNKNOWN suggests translation loss between hops, while INTERNAL suggests an origin service fault.
- -Inspect UNKNOWN example: backend returns INTERNAL with structured details, but an HTTP intermediary omits
grpc-status, and the client reports UNKNOWN. - -Inspect INTERNAL example: the origin service fails an internal invariant check in transaction logic and returns INTERNAL directly.
Correlation and Escalation Readiness
- -Link request IDs and trace spans across client, gateway, and service logs (example: one trace shows proxy reset before backend status serialization).
- -Package deterministic evidence for provider or platform escalation (example: same method, same payload shape, same region repeatedly returns UNKNOWN).
How to Verify the Fix
- -Replay the original failing flow and confirm responses return success or a more specific stable error class.
- -Verify UNKNOWN rates drop to baseline across the affected method and region.
- -Validate retries converge within configured caps without creating duplicate side effects.
How to Prevent Recurrence
- -Standardize explicit error-code mapping at service and gateway boundaries.
- -Preserve
google.rpc.Statusdetails end-to-end instead of flattening to generic messages. - -Alert on UNKNOWN spikes by method, region, and release version to catch regressions early.
Pro Tip
- -Add conformance tests that assert known failure paths never downgrade to UNKNOWN during translation.
Decision Support
Compare Guide
429 Too Many Requests vs 503 Service Unavailable
Use 429 for caller-specific throttling and 503 for service-wide outages, so retry behavior, escalation paths, and incident ownership stay correct.
Compare Guide
500 Internal Server Error vs 502 Bad Gateway: Root Cause
Debug 500 vs 502 faster: use 500 for origin failures and 502 for invalid upstream responses at gateways, then route incidents to the right team.
Playbook
API Timeout Playbook (502 / 504 / DEADLINE_EXCEEDED)
Use this playbook to separate invalid upstream responses from upstream wait expiration and deadline exhaustion, and apply timeout budgets, safe retries, and circuit-breaker controls safely.
Playbook
Availability and Dependency Playbook (500 / 503 / ServiceUnavailable)
Use this playbook to separate origin-side 500 failures from temporary 503 dependency or capacity outages, then apply safe retry and escalation paths.
Official References
Provider Context
This guidance is specific to GCP services. Always validate implementation details against official provider documentation before deploying to production.