grpcurl "Failed to dial target host: connection refused" in CI

By Daniel Zoghalchali·Latchkey

grpcurl tried to dial the host:port you passed and the connection was refused. Either nothing is listening there yet, the address is wrong, or you used plaintext against a TLS-only server (or vice versa).

What this error means

A grpcurl probe fails with "Failed to dial target host \"localhost:50051\": connection refused", usually in a smoke-test or health-check step before the integration suite.

Failed to dial target host "localhost:50051": context deadline exceeded:
connection error: desc = "transport: Error while dialing: dial tcp 127.0.0.1:50051: connect: connection refused"

Common causes

The server is not up or on a different port

grpcurl ran before the gRPC server bound its port, or the port differs from what was passed.

A plaintext/TLS scheme mismatch

Using -plaintext against a TLS server (or omitting it against a TLS server) can prevent the dial from completing.

How to fix it

Confirm the address and scheme, after the server is up

1. Wait until the port is open before probing with grpcurl.
2. Pass the exact host:port the server binds.
3. Match the transport: -plaintext for non-TLS, omit it (or pass certs) for TLS.

until nc -z localhost 50051; do sleep 1; done
grpcurl -plaintext localhost:50051 list

Probe a TLS server correctly

Drop -plaintext and supply the CA when the server requires TLS.

grpcurl -cacert ca.pem api.internal:443 list

How to prevent it

• Gate grpcurl probes on the port being open.
• Pass the correct host:port for the job network.
• Match grpcurl transport flags to the server's TLS configuration.

Frequently asked questions

Related guides

References

• GitHub Actions documentation