gRPC "rpc error: code = Unavailable desc = connection refused" in CI

By Daniel Zoghalchali·Latchkey

This is the Go gRPC form of an UNAVAILABLE failure: the TCP connection to the server's address was refused. Nothing is listening on that host:port yet, or it is the wrong address for the runner.

What this error means

A Go client or test fails with "rpc error: code = Unavailable desc = connection error: desc = \"transport: Error while dialing: dial tcp 127.0.0.1:50051: connect: connection refused\"".

rpc error: code = Unavailable desc = connection error: desc =
"transport: Error while dialing: dial tcp 127.0.0.1:50051: connect: connection refused"

Common causes

The server is not listening yet

The client dials before the gRPC server binds its port, so the OS refuses the connection.

Wrong address or unexposed container port

The dial target is the wrong host:port, or a service container's port is not published to the job network.

How to fix it

Wait for the listener before dialing

1. Start the server and wait until the port accepts connections.
2. Dial the exact host:port the server binds (127.0.0.1 vs service name in containers).
3. Publish the gRPC port for service containers.

until nc -z localhost 50051; do sleep 1; done
go test ./...

Block the dial until ready

Use a blocking dial with a timeout so the client waits for the server instead of failing instantly.

conn, err := grpc.DialContext(ctx, addr,
  grpc.WithTransportCredentials(insecure.NewCredentials()),
  grpc.WithBlock())

How to prevent it

• Wait on the gRPC port before running Go tests.
• Use the correct host for the network (localhost vs service name).
• Expose service-container ports to the job.

Frequently asked questions

Related guides

References

• GitHub Actions documentation