Skip to content

Troubleshooting

Jump to bottom
Will Luck edited this page Apr 13, 2026 · 5 revisions

Troubleshooting

Quick Reference

Symptom Action
Setup wizard expired Restart the container - opens a new 5-minute window
"permission denied" on Docker socket Mount with -v /var/run/docker.sock:/var/run/docker.sock:ro
No containers shown Verify Docker socket mount and permissions
Updates not detected Check SENTINEL_POLL_INTERVAL and SENTINEL_GRACE_PERIOD
Rate limit warnings Add Docker Hub credentials in Settings > Registries
Agent won't connect Check SENTINEL_SERVER_ADDR includes port; generate a new token
Agent shows "disconnected" Auto-reconnects; verify firewall allows the cluster port
WebAuthn not working Check SENTINEL_WEBAUTHN_RPID and SENTINEL_WEBAUTHN_ORIGINS
Dashboard not updating (SSE) Set proxy_buffering off; raise proxy_read_timeout to 86400
Container stuck in "updating" Restart Sentinel; maintenance labels clear on the next scan
Dashboard stuck on "Updating" after queue approval Upgrade to v2.12+; SSE reconnect now catches up stale badges
Cluster CA mismatch Re-enrol the agent: stop, delete cluster data dir, restart with new token
Portainer duplicate containers Engine ID dedup handles this automatically in v2.12+
CSRF errors Send sentinel_csrf cookie value as X-CSRF-Token header

Common Issues

"failed to load containers" on first start

The initial scan ran before setup completed. Fixed in v2.3.1: the scan now waits until the dashboard is loaded. On older versions this is harmless; the next scan cycle will succeed.

Setup wizard expired

The setup window is 5 minutes. Restart the container to open a new one:

docker restart docker-sentinel

Cannot connect to Docker socket

Error: Cannot connect to the Docker daemon at unix:///var/run/docker.sock

Verify the socket is mounted:

-v /var/run/docker.sock:/var/run/docker.sock:ro

On rootless Docker or Podman the socket path may differ. Set SENTINEL_DOCKER_SOCK to override.

Docker Hub rate limits

Account type Limit
Anonymous 100 pulls per 6 hours
Authenticated (free) 200 pulls per 6 hours
Pro / Team 5,000+ pulls per day

The dashboard Rate Limits stat card shows remaining quota. Add Docker Hub credentials via Settings > Registries to raise limits. For images with GHCR mirrors, Sentinel offers one-click migration from the container detail page.

SSE connection drops / dashboard not updating

  • Set proxy_buffering off on your reverse proxy. Required for SSE.
  • Raise proxy_read_timeout to at least 86400s.
  • Check that no CDN or caching layer is buffering responses.

WebAuthn not working

  • SENTINEL_WEBAUTHN_RPID must match your domain exactly (e.g. sentinel.example.com).
  • SENTINEL_WEBAUTHN_ORIGINS must include the full origin with scheme (e.g. https://sentinel.example.com). Multiple origins are comma-separated.
  • WebAuthn requires HTTPS (localhost is exempt).

Cluster agent not connecting

  1. Confirm the server is listening: SENTINEL_CLUSTER_PORT defaults to 9443.
  2. Verify the firewall allows the cluster port.
  3. Check SENTINEL_SERVER_ADDR includes the port (e.g. 192.168.1.10:9443).
  4. Enrolment tokens are single-use. Generate a new one if the first attempt failed.
  5. Check agent logs for certificate errors.

Cluster CA certificate mismatch

If the server's CA certificate was regenerated (e.g. the /data/cluster volume was deleted, or the server moved to a new host), agents with the old CA cached locally will fail to connect with TLS errors.

The agent logs an actionable error message once:

server CA mismatch -- the server's TLS certificate has changed since this agent enrolled
  fix="re-enroll this agent: stop it, delete the cluster data directory, and restart with a fresh SENTINEL_ENROLL_TOKEN"
  data_dir="/data/cluster"

Resolution:

  1. Stop the agent container.
  2. Delete the cluster data directory inside the agent volume (the path shown in data_dir).
  3. Generate a new enrolment token on the server (Cluster page or POST /api/cluster/enroll-token).
  4. Restart the agent with SENTINEL_ENROLL_TOKEN set to the new token.

The agent will re-enrol and receive a certificate signed by the server's current CA. The error is logged once per agent lifecycle to prevent log spam.

Portainer Engine ID duplicates

If the same Docker host is monitored by multiple sources (local socket, a Portainer endpoint, and a cluster agent), containers may appear duplicated in the dashboard.

From v2.12 onwards, Sentinel collects the Docker Engine ID from each source and compares them automatically. When two sources share the same Engine ID, the Portainer endpoint is flagged and excluded from scans. A source_overlap event appears in the SSE stream and the activity log.

No manual action is needed. If you see duplicate containers on older versions, check whether a Portainer endpoint is pointing at the same Docker host that Sentinel already monitors locally or via a cluster agent.

Dashboard stuck on "Updating" after queue approval

On versions before v2.12, approving a container update from the queue page could leave the dashboard showing a permanent "Updating" badge on that container. This happened when the SSE container_update event was sent between the server-side page render and the SSE connection being established, meaning the event was lost.

On v2.12+: This is fixed. The SSE reconnect handler now catches up by refreshing any rows that still show the "Updating" state when the connection is established.

On older versions: Reloading the page clears the stale badge. Alternatively, restart Sentinel; maintenance labels are cleared on the next scan cycle.

Container not updating

  1. Check the container's policy. pinned containers are never updated.
  2. Check whether the scheduler is paused (Settings > Scanning).
  3. Check container name filters (Settings > Scanning > Filters).
  4. For :latest tags: verify SENTINEL_LATEST_AUTO_UPDATE=true.
  5. Verify registry credentials if using a private registry.
  6. Check the activity log for errors.

Rollback not available

Rollback requires a pre-update snapshot taken by Sentinel. If the container was never updated by Sentinel, no snapshot exists. Check available disk space; snapshot data is stored in BoltDB.

Debug Logging

JSON structured logging is on by default (SENTINEL_LOG_JSON=true). For human-readable output:

-e SENTINEL_LOG_JSON=false

View logs:

docker logs docker-sentinel
docker logs -f docker-sentinel             # follow
docker logs --since 1h docker-sentinel     # last hour
docker logs --tail 100 docker-sentinel     # last 100 lines

The Logs page in the web UI records all actions and errors with full context.

Common Log Messages

Message Meaning
wizard server listening First-run setup mode - navigate to /setup
scheduler started Normal operation; scanning per the configured schedule
enrollment complete Agent successfully enrolled with the server
channel established Agent gRPC stream connected
entering autonomous mode Agent lost connection; operating independently
state report accepted Agent state synced to the server

Database

State is in BoltDB at /data/sentinel.db.

# Back up
docker cp docker-sentinel:/data/sentinel.db ./backup.db

# Full reset (wipes all data, setup wizard will reappear)
docker stop docker-sentinel
docker volume rm sentinel-data

Getting Help

  • GitHub Issues
  • Check Logs in the web UI for detailed error messages.
  • Include the Sentinel version (from Settings > About) and Docker version when reporting issues.

Home

Getting Started

Using Sentinel

Multi-Host

Security

Reference

Clone this wiki locally