Skip to content

Troubleshooting

The client cannot connect

  • health() returns healthy: false, status: "unreachable": the query URL is wrong or Jaeger is down. Check GROW_JAEGER_URL / JAEGER_QUERY_URL (default http://127.0.0.1:16686, the query port, not the OTLP ports 4317/4318) and that the port is reachable from where your code runs (inside Docker, 127.0.0.1 is the container itself).
  • health() returns status: "degraded": the query service answers but the healthcheckv2 endpoint at healthUrl (port 13133, /status) reports a problem; see the healthcheck.* entries in details.
  • The remote sampler never gets a strategy: check samplingUrl (GROW_JAEGER_SAMPLING_URL / JAEGER_SAMPLING_ENDPOINT, default http://127.0.0.1:5778/sampling). Until the first poll succeeds it samples at initialSamplingRate (0.001); a failed poll keeps the last strategy.
  • Calls fail with UNAVAILABLE after several seconds: the client retried with backoff. Lower maxRetries or totalTimeout to fail faster.
  • Behind a corporate proxy: HTTP_PROXY/HTTPS_PROXY are ignored on purpose. Set proxy (or GROW_JAEGER_PROXY).

CONFIG errors

The message names the setting or environment variable, never its value. Typical causes: a URL without http:// or https://, a duration such as 10 sec (use 10s or 10000), a client certificate without its key, MAX_RETRIES below 0.

AUTHENTICATION or PERMISSION_DENIED

  • ping() is the quickest credential check: it makes one authenticated call.
  • Stock Jaeger has no authentication. AUTHENTICATION/PERMISSION_DENIED come from a reverse proxy in front of it: set its bearer token in token (GROW_JAEGER_TOKEN), which is sent as Authorization: Bearer <token> on query and sampling requests. health() never sends it.
  • Explicit config values win over the environment (see Service settings).
  • The SDK never prints credentials, so toString() of the config shows [REDACTED] even when a credential is set.

TLS errors

  • Self-signed or private CA: set tls.caCertPath (GROW_JAEGER_CA_CERT).
  • Mutual TLS: set both tls.clientCertPath and tls.clientKeyPath.
  • tls.insecureSkipVerify only for local tests.

RATE_LIMITED

The service asked the client to slow down. The client waits for Retry-After up to maxRetryAfter (60 s); longer waits fail at once with retryAfter set on the error so your code can schedule a later attempt.

TIMEOUT

requestTimeout (30 s) bounds one attempt and totalTimeout (120 s) the whole call including retries. Raise them for slow operations, or pass a per-call deadline (signal, ctx, cancel token, future timeout).

See what the client does

Turn on the logger or add hooks: both see every attempt with redacted headers and URLs.

Docker integration tests fail

  • Run one language: make test-docker LANGS=go.
  • In CI, download the compose-logs-<lang> artifact of the failed job.
  • Locally, the stack is removed after each run; rerun with Docker logs open (docker compose -f docker/compose.yml logs -f) in a second terminal.

Traces do not show up

  • Spans go to the OTLP ports (HTTP 4318, gRPC 4317), not to the query port 16686. Check GROW_JAEGER_OTLP_HTTP_ENDPOINT / OTEL_EXPORTER_OTLP_ENDPOINT (see Tracing setup).
  • Spans are batched: call forceFlush() or shutdown() on the tracing handle before you query. An exported span is queryable about 200 ms after the export ack, so poll with waitForTrace instead of a single getTrace.
  • With the remote sampler, the initial rate is 0.001 until the first strategy arrives, so most early traces are not sampled. Use SamplingPreset.development (always on) in tests.

Still stuck?

Open an issue with the language, package version, Jaeger version and a minimal reproduction (with secrets removed): https://github.com/grow-codes-packages/jaeger/issues.