Troubleshooting

This page is organised by what you see, not by what's broken under the hood. Start at the symptom that matches.

Symptom: I open the UI and nothing happens / connection refused

1. 1

   Are the containers up?

   docker compose ps

   Every row should say running and healthy. If orbtrace is exited, run docker compose logs orbtrace | tail -200 and look for the failure reason — usually it's a missing env var (PGPASSWORD not set), or PostgreSQL not yet reachable.

2. 2

   Is the UI port reachable?

   curl -I http://localhost:8080

   Should return 200 or 302. If connection refused, either the server isn't up yet (give Doris its 2–3 minutes) or port 8080 is taken — remap it in docker-compose.yml, or stop the conflicting service. (Orbtrace serves plain HTTP on 8080 by default; 80/443 only exist if you enabled the Caddy edge profile or your own proxy.)

3. 3

   Is the backend healthy?

   curl -sf http://localhost:8080/actuator/health

   Expect {"status":"UP"}. If DOWN, the components array tells you which dependency is failing (db, doris, valkey).

Symptom: I can sign in but no data appears (any pillar)

1. 1

   Are the apps sending?

   On the host running your app:

   nc -zv <orbtrace-host> 4317

   Should say succeeded. If it doesn't, you have a network/firewall problem — open the port.

2. 2

   Did the Collector accept the data?

   docker logs orbtrace-otelcol | tail -100

   (Use the name of the Collector you run — Orbtrace doesn't bundle one.) Look for accepted_spans, accepted_logs, refused_spans. Refusals usually mean: an auth header your Collector requires but the app doesn't send, or a protocol mismatch (HTTP body sent to the gRPC port or vice versa).

3. 3

   Did Doris receive it?

   docker compose exec doris-fe mysql -u root -e \
     "SELECT count(*) FROM orbtrace.otel_logs WHERE timestamp >= now() - interval 5 minute"

   Non-zero? Then the data is in storage and the problem is the read path / time picker. Zero? Then the Collector is dropping it — check otelcol logs (step 2 again) and the exporter section.

4. 4

   Is the UI's time picker right?

   The single most common cause of "no data" is a time picker set to a window before your data arrived. Click the time picker → "Last 15 m" → re-check.

5. 5

   Sampling dropping too much?

   If only some data is missing, look at Admin → Sampling. Verify that keep errors and keep slow overrides are on. Set the global base rate to 1.0 temporarily — if data reappears, you over-sampled.

Symptom: Doris BE is unhealthy

1. 1

   Check the Doris BE log

   docker compose logs doris-be | tail -200

2. 2

   Look for MEM_LIMIT_EXCEEDED

   Doris BE has a hard memory ceiling (mem_limit in be.conf). Exceeding it crashes the BE. Symptoms: write success rate drops, Health page shows red. Fix:

   • Tame ingestion rate (lower seed throughput, narrow sampling).
   • Increase mem_limit if the host has the RAM.
   • On a laptop M-series running the dev stack: keep combined inflow under ~25K events/sec.
3. 3

   Look for storage exhaustion

   Doris stops writes when disk is over 95%. df -h on the host. If you're near the cap, shorten telemetry retention — that's set by the Doris profile (lower doris.profile.retention.*, in days, or pick a tighter small / medium / large tier) and reclaims partitions on the next sweep — or add disk. (Telemetry retention is a Doris-profile setting, not an ORBTRACE_* env var.)

Symptom: RCA is broken / "AI provider failed"

1. 1

   Test the provider connection

   Admin → AI → Test connection. The button surfaces the exact error from the SDK.

2. 2

   Read common SDK errors

   • 401 Unauthorized → wrong API key. Re-paste.
   • 403 Forbidden → key valid but your org is rate-limited or the model is disabled.
   • Timeout → upstream is slow; increase SPRING_AI_RETRY_BACKOFF_MAX_INTERVAL.
   • Budget exceeded → you're past ORBTRACE_AI_BUDGET_MONTHLY_USD. RCA is intentionally disabled until next month or until you raise the cap.
3. 3

   If you use Ollama, is the host reachable from the orbtrace container?

   The base URL must be reachable from inside the docker network — http://ollama:11434 works only if ollama is also a container on the same compose network. From outside, you need to expose the port and use the host's IP. See OLLAMA_BASE_URL.

Symptom: The login page rejects credentials (or shows no buttons)

1. 1

   No login buttons at all?

   No SSO provider is configured (every client-id is empty or still change-me). Set at least one provider's credentials and restart — see Authentication. There is no hidden local-login URL; Orbtrace only shows what you configured.

2. 2

   Using the local eval login?

   If you set ORBTRACE_BOOTSTRAP_ADMIN_PASSWORD (alongside ORBTRACE_BOOTSTRAP_ADMIN_USERNAME), sign in with that exact email and password. A password set without a username aborts startup, so if the server is up and the form is missing, the username is also set. There is no admin@nivorbit.local default and no auto-generated password.

3. 3

   SSO sign-in fails after the IdP

   Almost always a redirect-URI mismatch: the URI registered in your IdP must be exactly {ORBTRACE_BACKEND_URL}/login/oauth2/code/{provider} (google/microsoft/github/oidc). The server log prints a one-line reason at WARN — invalid_client, redirect_uri_mismatch, or missing email (the IdP didn't return an email claim).

4. 4

   Signed in, then immediately bounced out?

   The server clock is skewed, so tokens look expired. Check the host time against NTP within a few seconds.

Symptom: UI is slow, charts take 10+ seconds

1. 1

   Time window too wide?

   "Last 30 d" over a busy fleet scans hundreds of GB. Narrow the time picker. If a chart needs 30 d, build it from pre-aggregated metric queries, not from spans.

2. 2

   Doris BE busy?

   Admin → Health → Doris. If slow queries is climbing or BE CPU is at 100%, the cluster is under-provisioned for your read load. Two options: scale Doris BEs, or raise ORBTRACE_DORIS_POOL_MAX_SIZE to handle concurrent users without queueing.

3. 3

   High-cardinality group-by?

   Group-by on user_id will draw thousands of series and slow the page. Group by lower-cardinality attributes (service, route, region).

Symptom: Two services should connect on the map, but the edge is missing

1. 1

   Verify trace context propagation

   Both services need to be running OTel-instrumented. The caller must send the W3C traceparent header. The callee must extract it. Auto-instrumentation does this for HTTP and gRPC out of the box; bespoke transports (raw sockets, queues, FTP) need manual span links.

2. 2

   For queue-based calls, enable Async Stitching

   Kafka, RabbitMQ, SQS, Redis Streams calls are stitched after ingest by Orbtrace's async-stitching job. If you don't see those edges, check Admin → Health → Background jobs → Async stitching — it should be running every 30 s.

3. 3

   Check the time window

   The map only draws edges that had at least one call in the window. If you set "Last 5 m" and the call only happens hourly, the edge will be missing.

Symptom: One container restarts every few minutes

docker compose ps -a | grep -i restart
docker compose logs <name> --since 10m

Common causes:

• Out-of-memory kill — dmesg | grep -i kill on the host shows OOM events. Raise the container's memory limit or the host's RAM.
• Liveness probe failure — the container reports unhealthy because a downstream is down. Look at the first error in the log; it usually points to the real culprit.
• Bad config — env var typo, malformed YAML. Logs are explicit; read them.

Symptom: "Could not bind to port" on startup

Either the port is taken by another process on the host or another container claimed it first. lsof -i :4317 or ss -tlnp | grep 4317 identifies the holder. Either stop the holder or remap the port in docker-compose.yml.

Symptom: Postgres logs chmod ... /var/run/postgresql: Operation not permitted on OpenShift

Harmless — not an error. The bundled Postgres image (upstream postgres, which pgvector/pgvector builds on) chmods its socket directory on startup. Under OpenShift's restricted-v2 SCC the pod runs as an arbitrary assigned UID that doesn't own that directory, so the chmod can't change it and prints the line (the image skips it with || :). It is not introduced by the Orbtrace chart. Postgres starts normally — confirm with the log lines right after (database system is ready to accept connections) and oc get pod -l app.kubernetes.io/component=postgres showing Running. Nothing to fix.

When you have to escalate

If none of the above resolves it, capture:

1. docker compose ps
2. docker compose logs --since 30m > orbtrace-debug.log
3. The Admin → Health screenshot.
4. Browser DevTools network tab if the symptom is UI-side.

Send the bundle to support (Premium tier) or open a GitHub issue (Standard). The five things above resolve about 90% of tickets without follow-up questions.

Next: FAQ.