go network_error ai_generated true

rpc error: code = Unavailable desc = the server is currently shutting down

ID: go/grpc-unavailable-server-shutdown

Also available as: JSON · Markdown · 中文
80%Fix Rate
84%Confidence
0Evidence
2025-07-30First Seen

Version Compatibility

VersionStatusIntroducedDeprecatedNotes
1.0 active — — —
1.1 active — — —

Root Cause

The gRPC server is in the process of graceful shutdown and is not accepting new requests.

generic

中文

gRPC服务器正在优雅关闭过程中，不接受新请求。

Workarounds

  1. 80% success Implement retry with backoff to wait for the server to restart. 
    for i := 0; i < 5; i++ {
    resp, err := client.SomeRPC(ctx, req)
    if err == nil { return resp }
    if status.Code(err) != codes.Unavailable { return err }
    time.Sleep(time.Duration(1<<i) * time.Second)
}
  2. 85% success Use a load balancer to redirect requests to healthy instances. 
    Configure a load balancer that detects server health and routes traffic away from shutting down instances.

Dead Ends

Common approaches that don't work:

  1. Retry the request immediately. 90% fail

    The server is still shutting down; it may take some time to become available again.

  2. Force the server to stop shutdown. 100% fail

    Shutdown is initiated by the server; clients cannot override it.