SECURITY WARNING: Never run commands you don't understand. Always review code before execution. Use at your own risk.
FixMyError.net
gRPC 10 errors

gRPC Status Code Errors

Status codes, deadlines, message limits, TLS and HTTP/2 transport failures.

Understanding gRPC errors

Every gRPC call ends with a status code, and the code tells you which layer failed. UNAVAILABLE and INTERNAL are transport: the connection, the proxy or the HTTP/2 stream, not your handler. UNAUTHENTICATED, PERMISSION_DENIED and UNIMPLEMENTED mean the request arrived and was rejected before your logic ran. INVALID_ARGUMENT, FAILED_PRECONDITION and ABORTED are your service answering deliberately. The distinction matters most for retries: UNAVAILABLE and ABORTED are safe to retry, FAILED_PRECONDITION and INVALID_ARGUMENT never are, and retrying them turns one bad request into a storm.

How to debug gRPC errors

  1. Read the code and the message together. grpcurl -vv prints the status, the message and any google.rpc error details the server attached, which is far more than most client libraries surface by default.
  2. Establish whether the call reached your handler at all. Log at the first line of the method: if nothing appears, the failure is in the transport, the proxy or an interceptor, and reading your business logic is wasted effort.
  3. Enable the runtime's own transport logging. GRPC_GO_LOG_SEVERITY_LEVEL=info GRPC_GO_LOG_VERBOSITY_LEVEL=2 for Go, or GRPC_VERBOSITY=debug GRPC_TRACE=http,call_error for the C based implementations, exposes HTTP/2 resets and name resolution that the status code hides.
  4. Check that HTTP/2 survives the whole path. Any load balancer that terminates at layer 7 without HTTP/2 support, or an idle timeout shorter than your keepalive, produces stream resets that surface as INTERNAL or UNAVAILABLE on a service that is perfectly healthy.
  5. Confirm both sides were generated from the same .proto. A method rename, a package change or a stale generated file gives UNIMPLEMENTED, and grpcurl list against a server with reflection enabled settles it in one command.
  6. For anything size or time related, remember the limits are enforced per side: the 4 MB receive limit, the client deadline and the server's max connection age each belong to one peer, so raising one alone often just moves the failure.

Tools worth reaching for

  • grpcurl
  • grpc_health_probe
  • GRPC_GO_LOG_SEVERITY_LEVEL / GRPC_TRACE
  • buf lint && buf breaking
  • Wireshark or tcpdump with HTTP/2 decoding
  • Envoy access logs

All 10 gRPC errors

Other categories