gRPC "UNAVAILABLE: failed to connect to all addresses" in CI

gRPC status 14 UNAVAILABLE with "failed to connect to all addresses" means the channel tried every address the target resolved to and none accepted the connection. The server is down, not listening, or unreachable from the runner.

What this error means

An integration test fails with "Error: 14 UNAVAILABLE: failed to connect to all addresses" or "...; last error: Connection refused". It typically hits a service that has not finished starting.

Error: 14 UNAVAILABLE: failed to connect to all addresses;
last error: UNKNOWN: ipv4:127.0.0.1:50051: Failed to connect to remote host: Connection refused

Common causes

The server has not started or bound the port yet

The client connects before the gRPC service is listening, so every address refuses the connection.

A wrong host, port, or unexposed service container

The target points at the wrong address, or the service container's port is not reachable from the job, so no address connects.

How to fix it

Wait for the server to be reachable

1. Start the gRPC server and wait until its port accepts connections before running tests.
2. Confirm the client targets the exact host:port the server binds.
3. For service containers, expose the gRPC port to the job.

# block until the gRPC port is open
until nc -z localhost 50051; do sleep 1; done

Probe the server with grpcurl

Confirm the server answers before tests run so a refused connection is caught early.

grpcurl -plaintext localhost:50051 grpc.health.v1.Health/Check

How to prevent it

• Wait on the gRPC port before starting tests in CI.
• Pin client target host:port to the server bind address.
• Expose service-container ports to the job that needs them.

Related guides