Troubleshooting¶
The client cannot connect¶
health()returnshealthy: false, status: "unreachable": the query URL is wrong or Jaeger is down. CheckGROW_JAEGER_URL/JAEGER_QUERY_URL(defaulthttp://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.1is the container itself).health()returnsstatus: "degraded": the query service answers but the healthcheckv2 endpoint athealthUrl(port 13133,/status) reports a problem; see thehealthcheck.*entries indetails.- The remote sampler never gets a strategy: check
samplingUrl(GROW_JAEGER_SAMPLING_URL/JAEGER_SAMPLING_ENDPOINT, defaulthttp://127.0.0.1:5778/sampling). Until the first poll succeeds it samples atinitialSamplingRate(0.001); a failed poll keeps the last strategy.
- Calls fail with
UNAVAILABLEafter several seconds: the client retried with backoff. LowermaxRetriesortotalTimeoutto fail faster. - Behind a corporate proxy:
HTTP_PROXY/HTTPS_PROXYare ignored on purpose. Setproxy(orGROW_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_DENIEDcome from a reverse proxy in front of it: set its bearer token intoken(GROW_JAEGER_TOKEN), which is sent asAuthorization: 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.clientCertPathandtls.clientKeyPath. tls.insecureSkipVerifyonly 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()orshutdown()on the tracing handle before you query. An exported span is queryable about 200 ms after the export ack, so poll withwaitForTraceinstead of a singlegetTrace. - 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.