◆Error Codes Wiki

gRPC Status DEADLINE_EXCEEDED — Request Timeout Before Completion

Warning5xx server error

Overview

Fix gRPC DEADLINE_EXCEEDED status code (4) when an RPC call does not complete within the configured deadline or timeout period.

Key Details

  • gRPC status code 4 (DEADLINE_EXCEEDED) means the operation did not finish before the client's deadline
  • Every gRPC call should have a deadline — calls without deadlines can hang indefinitely
  • Deadlines propagate through the call chain: if service A calls B calls C, C inherits A's remaining deadline
  • This is functionally similar to HTTP 504 Gateway Timeout but with explicit deadline semantics
  • The server may still be processing the request after the client receives this error

Common Causes

  • Client deadline set too short for the operation being performed
  • Server processing time increased due to load, slow dependencies, or inefficient code
  • Network latency between client and server consuming most of the deadline budget
  • Downstream service calls in a chain consuming the propagated deadline

Steps

  1. 1Review and increase the client deadline if it is too aggressive for the operation type
  2. 2Profile the server-side handler to identify slow operations — database queries, external API calls
  3. 3Implement deadline propagation correctly: pass context with deadline to all downstream calls
  4. 4Add server-side deadline checking: if ctx.Err() == context.DeadlineExceeded, return early to save resources
  5. 5Use streaming RPCs for operations that return large datasets instead of single unary calls

Tags

grpcdeadlinetimeoutstatus-4performance

Related Items

http-grpc-status-code-unavailable

More in 5xx Server Error

http-500-internal-server-errorHTTP 500 Internal Server Error — What It Means & How to Fix It
Critical
http-501-not-implementedHTTP 501 Not Implemented — What It Means & How to Fix It
Critical
http-502-bad-gatewayHTTP 502 Bad Gateway — What It Means & How to Fix It
Critical
http-503-service-unavailableHTTP 503 Service Unavailable — What It Means & How to Fix It
Critical
http-504-gateway-timeoutHTTP 504 Gateway Timeout — What It Means & How to Fix It
Critical
http-505-http-version-not-supportedHTTP 505 HTTP Version Not Supported — What It Means & How to Fix It
Critical

Frequently Asked Questions

There is no universal default. Set deadlines based on the operation: 500ms for simple lookups, 5s for database operations, 30s for complex computations. Never use no deadline — it risks hanging calls.