gRPC — status 14 unavailable from server

gRPC returns status 14 UNAVAILABLE because the server is down, the connection was reset, or keepalive pings were not answered within the timeout.

intermediatedebugginggrpcnetwork

Symptoms

error: 14 UNAVAILABLE: connection refused
Intermittent 14s under load but stable when idle
Works with grpcurl but not from the application

Possible causes

The server is not running or crashed
Keepalive ping timeout is too aggressive for the network
The connection pool is exhausted or max concurrent streams reached

Diagnosis steps

Test the server directly

grpcurl -plaintext localhost:9090 list

Interpretation

If grpcurl fails, the server is down; if it works, the issue is client-side.

Check keepalive settings

grep -n "keepalive|keepAlive" src/grpc-client.ts

Interpretation

Compare keepAliveTimeMs and keepAliveTimeoutMs against network RTT.

Root cause

The gRPC server is unreachable or did not respond to keepalive pings within the timeout, so the client reports status 14 UNAVAILABLE.

Fix

Restart the server, tune keepalive parameters, add retry with backoff, or increase the connection pool size. Monitor server health with readiness checks.

Verify the fix

Call the gRPC method and confirm a successful response; verify retry logic handles transient 14s.

Symptom walkthrough

gRPC returns status 14 UNAVAILABLE because the server is down, the connection was reset, or keepalive pings were not answered within the timeout. The error appears in production but may not surface in local development because the conditions that trigger it depend on the deployment environment or runtime configuration. Understanding the full symptom set helps distinguish this issue from similar errors.

Diagnosis in practice

Follow the diagnosis steps in the frontmatter to isolate the cause. Each step includes a command and an interpretation of the output. The goal is to narrow down whether the issue is in the configuration, the runtime, or the application code. Reproduce the error in a minimal setup before applying a fix.

Root cause

The gRPC server is unreachable or did not respond to keepalive pings within the timeout, so the client reports status 14 UNAVAILABLE.

Fix

Restart the server, tune keepalive parameters, add retry with backoff, or increase the connection pool size. Monitor server health with readiness checks. After applying the fix, monitor the system to confirm the error does not recur under load or in different environments.

Verification

Call the gRPC method and confirm a successful response; verify retry logic handles transient 14s. If the verification passes, the fix is confirmed; if not, re-examine the diagnosis steps for missed contributing factors.

Diagnostic commands

Run these commands to reproduce and diagnose the issue:

grpcurl -plaintext localhost:9090 list
grep -n "keepalive|keepAlive" src/grpc-client.ts