Troubleshooting¶
The client cannot connect¶
health()returnshealthy: false, status: "unreachable": the URL is wrong or the service is down. CheckGROW_SIGNOZ_URL(defaulthttp://127.0.0.1:8080) and that the port is reachable from where your code runs (inside Docker,127.0.0.1is the container itself).- 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_SIGNOZ_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.- Make sure the key variable is the one this SDK reads (
GROW_SIGNOZ_API_KEY, thenSIGNOZ_API_KEY); explicit config values win over the environment. Without any key, query calls raiseCONFIGbefore sending anything. - The key must be a SigNoz service-account API key (Settings → Service accounts), not a SigNoz Cloud ingestion key and not a user session token. Any role works for queries.
- The SDK never prints credentials, so
toString()of the config shows[REDACTED]even when a key is set.
Logs or spans do not show up¶
- Ingest goes to the collector (
otlpEndpoint, defaulthttp://127.0.0.1:4318), not to the query URL (port 8080). CheckGROW_SIGNOZ_OTLP_ENDPOINTandGROW_SIGNOZ_OTLP_PROTOCOL(grpcuses port 4317). - The log client batches: call
flush()(orclose()the client) before you exit, and checkstats()fordroppedandfailedrecords. - New data is queryable after a few seconds; use
waitForLog/waitForTracein tests. - SigNoz Cloud needs
ingestionKey(GROW_SIGNOZ_INGESTION_KEY/SIGNOZ_INGESTION_KEY).
A query returns no rows¶
- An unknown field in the filter does not fail: SigNoz returns no rows plus a warning. Read
warningson the result or turn on the logger (warnings are logged at warn level). - The default window is the last hour; pass
start/endfor older data. CONTAINSis a LIKE pattern on the server; theFilterBuilderescapes%and_for you, a raw expression does not.
UNSUPPORTED¶
serverVersion()on the official community image: it reports an empty version.- Any call to a route the server does not have: SigNoz answers unknown routes with its web UI
(
200 text/html), which the SDK maps toUNSUPPORTED. Check thaturlpoints at the SigNoz query service (port 8080) and that the server version matches Compatibility.
TLS errors¶
- Self-signed or private CA: set
tls.caCertPath(GROW_SIGNOZ_CA_CERT). - Mutual TLS: set both
tls.clientCertPathandtls.clientKeyPath. tls.insecureSkipVerifyonly for local tests. Over OTLP/gRPC it is not honoured by every language (Compatibility); add the CA withtls.caCertPathor usehttp/protobuf.
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.
Still stuck?¶
Open an issue with the language, package version, SigNoz version and a minimal reproduction (with secrets removed): https://github.com/grow-codes-packages/signoz/issues.