gRPC Status UNAVAILABLE — Service Temporarily Unreachable or Overloaded

Fix gRPC UNAVAILABLE status code (14) when the service endpoint cannot be reached due to server overload, network issues, or service discovery failures. This guide covers everything you need to know about this topic, including common causes, step-by-step solutions, and answers to frequently asked questions.

Here are the key things to understand: gRPC status code 14 (UNAVAILABLE) indicates the service is temporarily unable to handle the request. This is the gRPC equivalent of HTTP 503 Service Unavailable. UNAVAILABLE is a transient error that should be retried with exponential backoff. Common in microservice architectures when downstream services are deploying, scaling, or experiencing load. gRPC uses HTTP/2 as its transport protocol, so network issues affecting HTTP/2 can trigger this. Understanding these fundamentals will help you diagnose and resolve this issue more effectively.

The most common reasons this occurs include: Target gRPC service is down, restarting, or in the process of deploying. DNS resolution failed for the service endpoint in Kubernetes or service mesh. Load balancer or service mesh (Istio, Envoy) cannot route to a healthy backend. Connection pool exhausted due to high request volume without proper connection management. Identifying the root cause is the first step toward finding the right solution.

To resolve this, follow these recommended steps: Implement retry logic with exponential backoff and jitter for UNAVAILABLE errors. Verify the service endpoint is correct and DNS resolves: nslookup service-name.namespace.svc.cluster.local. Check service health in Kubernetes: kubectl get pods -l app=service-name and inspect readiness probes. Review load balancer and service mesh configuration for proper health checks and circuit breaking. Monitor connection pool metrics and increase max connections if the pool is exhausted. If these steps do not resolve the issue, consider consulting additional resources or a qualified professional.

This article is part of our HTTP Status Codes collection on Error Codes Wiki. We provide comprehensive, up-to-date information to help you find solutions quickly.