sentinel docs

Reference

Troubleshooting

Common Sentinel failures and how to fix them. Group: dev config, Docker, OTLP, LLM/model, database, UI, and live reload.

This page covers the failures that come up most often. If something is not listed here, run sentinel check --offline first; it surfaces config and database issues before any LLM call.

sentinel dev says “.sentinel.yml not found”

The repo has not been initialized yet, or you ran the command from outside the repo root.

cd <repo-root>
sentinel dev init

If you are running non-interactively (CI, a script, an editor task), the wizard cannot prompt you. Generate the file once interactively and commit it.

sentinel dev errors on the config file

Common causes:

  • version is not 1 (or missing). Currently the only supported value is 1.
  • A service has neither command (for type: command) nor service (for type: compose_service).
  • A compose_service references a path directory that does not contain a Compose file, or that Compose project does not contain the named service.
  • defaults.group names a group that is not declared under groups.

Run sentinel dev doctor to get a per-check report. Add --json for machine-readable output.

sentinel dev doctor
sentinel dev doctor --group api-only --json

sentinel docker is not watching the right containers

Sentinel auto-discovers a Compose project first, then falls back to all running containers. If two Compose projects are running, or some containers are unmanaged, the selection can surprise you.

sentinel docker list
sentinel docker explain
sentinel docker explain api worker

list shows what would be watched. explain shows why each container was included or skipped. Override with explicit container names, or pass --all-running to ignore Compose detection entirely.

OTLP port 4318 is already in use

Something else (Jaeger, an OTel Collector, another sentinel instance) is on the default port. Pick a different one and point your exporter at it.

sentinel dev --otlp-http-addr 127.0.0.1:14318

For SDK-based exporters, set OTEL_EXPORTER_OTLP_ENDPOINT=http://127.0.0.1:14318 so they match.

Health-check or metrics traces are missing

That is the noisy-route filter doing its job. By default Sentinel keeps 20% of traces whose root path matches patterns like /health, /ready, /live, /metrics, and a few polling endpoints. Bump the ratio or remove the patterns:

sentinel dev \
  --otlp-noisy-trace-sample-ratio 1.0 \
  --otlp-noisy-route-patterns ""

See OpenTelemetry for the full list.

LLM triage fails or times out

Run a connectivity check:

sentinel check
sentinel check --base-url http://localhost:11434/v1 --model qwen2.5-coder

Common causes:

  • The local LLM server is not running. Start Ollama or LM Studio first.
  • The configured model is not pulled. ollama pull qwen2.5-coder:7b (or change --model to one you have).
  • The base URL is wrong. Defaults to http://localhost:11434/v1 for Ollama; LM Studio typically uses http://localhost:1234/v1.

If the LLM is reachable but slow, Sentinel falls back to the heuristic triage path after a 25-second timeout. You can run entirely without an LLM by passing --offline.

API key is not being applied

Order of resolution: explicit --api-key, then SENTINEL_API_KEY, then the Settings page value (encrypted in SQLite), then no key.

If you change the API key in the Settings page and the running process keeps using the old one, the live-reload signal did not reach it. Live reload is a Unix-only SIGHUP; on Windows, restart the command. On Unix, make sure the box “Signal running Sentinel processes to reload settings immediately” is checked when you save.

If the API key seems to disappear after a restart and you have not deleted it, check that ~/.sentinel/sentinel-master.key still exists. Without that file, the encrypted key in the database cannot be decrypted.

“no such table” or schema errors

Sentinel migrates the database on every startup. If you see schema errors, you most likely have an old binary pointing at a database written by a newer one. Update first:

sentinel update

If that does not resolve it and you can afford to start fresh, point at a different DB path with --db /tmp/sentinel.db to confirm it is a database-state issue rather than the binary.

UI is empty after starting sentinel ui

The UI shows what is in the database. If you just started Sentinel and have not ingested anything yet, the feed is empty by design. Try one of:

  • sentinel docker (in another terminal)
  • sentinel run -- <your command>
  • piping logs: cat app.log | sentinel stdin

Once events arrive, the UI updates without a refresh via the live status SSE stream. The footer indicator should read live (green). If it stays reconnecting or offline, you are likely behind a proxy that strips SSE; the UI falls back to polling and works, just with a delay.

sentinel dev stop hangs or “Graceful stop timed out”

The supervisor did not respond to SIGINT within 8 seconds. That is usually a wedged child process holding things open. Force the kill:

sentinel dev stop --force

After a force-stop, the runtime state file is also cleaned up. If a future sentinel dev complains about a stale state file, run sentinel dev status (it cleans up on a stale check) or delete the state file under ~/.sentinel/run/.