OpenTelemetry exporter "connection refused" in CI

By Daniel Zoghalchali·Latchkey

An OTLP exporter tried to connect to the collector endpoint and got "connection refused": the host resolved and was reachable, but no process was listening on that port. The target address is right; the receiver is not up.

What this error means

Logs show "connection refused" / "dial tcp 127.0.0.1:4317: connect: connection refused" from the SDK exporter or a collector forwarding to another collector.

failed to export traces: rpc error: code = Unavailable desc = connection error:
desc = "transport: Error while dialing: dial tcp 127.0.0.1:4317: connect: connection refused"

Common causes

The collector is not running yet

The exporter starts before the collector service container is ready, so the port is closed and the dial is refused.

Wrong port or host for the OTLP receiver

Exporting to 4317 (gRPC) when the receiver listens on 4318 (HTTP), or to localhost when the collector is another container, refuses the connection.

How to fix it

Start the collector and wait for the port

1. Bring up the collector before the step that exports telemetry.
2. Wait until the OTLP port accepts connections.
3. Then run the workload that exports.

until nc -z localhost 4317; do sleep 1; done
# now run the instrumented job

Match endpoint protocol and port

Use 4317 for gRPC OTLP and 4318 for HTTP OTLP, and point at the correct service host.

env:
  OTEL_EXPORTER_OTLP_ENDPOINT: http://otel-collector:4318

How to prevent it

• Start the collector and health-check its port before exporting.
• Use the gRPC (4317) or HTTP (4318) port that matches your exporter.
• Reference the collector by its service hostname, not localhost, across containers.

Frequently asked questions

Related guides

References

• GitHub Actions documentation