Jaeger client "connection refused" on UDP 6831 (thrift-compact agent) in CI

By Kaveh Alemi·Latchkey

Legacy Jaeger clients send spans to a local jaeger-agent over UDP on port 6831 (compact thrift). In CI no agent runs, so the reporter cannot deliver spans; UDP hides the failure but the client logs reporter errors or drops spans.

What this error means

Test logs show a Jaeger reporter error such as "error reporting span" / "connection refused" for localhost:6831, or spans silently never arrive because the UDP socket has no listener.

ERROR: jaeger.reporter could not send span:
write udp 127.0.0.1:0->127.0.0.1:6831: connect: connection refused

Common causes

No jaeger-agent on UDP 6831

The client defaults to localhost:6831 for the compact-thrift agent. Without a running agent (or the all-in-one image) in CI, nothing receives the UDP datagrams.

Tracing enabled unconditionally in tests

The tracer is initialized with the UDP reporter regardless of environment, so tests attempt to report to a nonexistent agent.

How to fix it

Use a no-op / const sampler with no reporter in tests

1. Disable the Jaeger reporter (or set a null reporter) when running tests.
2. If you must exercise reporting, run the Jaeger all-in-one as a service.
3. Prefer OTLP + an in-memory exporter for span assertions.

services:
  jaeger:
    image: jaegertracing/all-in-one:latest
    ports: ['6831:6831/udp', '16686:16686']

Disable tracing via env in test jobs

Set the client to disabled so no reporter is created.

env:
  JAEGER_DISABLED: 'true'

How to prevent it

• Disable the Jaeger reporter in unit test environments.
• Run jaeger all-in-one as a service only when reporting is under test.
• Migrate from the deprecated UDP agent to OTLP where possible.

Frequently asked questions

Related guides

References

• GitHub Actions documentation