Troubleshooting

Start with service state, then use the repository’s health checks and focused logs.

Repository-validated operator guidance View source ↗

#First response

Control-plane diagnosis

./scripts/healthcheck.sh
./scripts/diagnose.sh
cd infra && docker compose -f compose.yml -f compose.production.yml --env-file .env ps
cd infra && docker compose -f compose.yml -f compose.production.yml --env-file .env logs --tail 200 api daemon postgres redis web

#Common failures

Symptom	Likely cause	Check and fix
Beacon offline	Wrong ID/token, unreachable PANEL_API_URL, or Docker failure	Check standalone Beacon logs, then verify the three required variables and curl the panel API from the node.
SFTP refused	No listener or restrictive bind/firewall	Inspect DAEMON_SFTP_ADDR and DAEMON_SFTP_BIND_ADDR; use ss -lnt and the Beacon logs.
API unhealthy	PostgreSQL, migration, Redis, or secret configuration	Run scripts/healthcheck.sh and inspect API/PostgreSQL logs.
PostgreSQL auth failure	DATABASE_URL and POSTGRES credentials differ	Compare infra/.env values and reconnect with the Compose exec command.
TLS issuance fails	DNS/port 80/IPv6/proxy conflict	Use dig, confirm 80/443 ownership, then inspect Traefik logs.
Container will not start	Image, allocation, disk, or Docker failure	Inspect Beacon logs and Docker state on the assigned node.
Cron never runs	Disabled or invalid schedule; API unavailable	Confirm the saved schedule, enable it, then inspect API logs after restart.
Backup restore fails	Destination cannot reach repository or lacks capacity	Verify object-storage credentials from the node and the destination data path before retrying.

#Escalate safely

Do not delete data to make an error disappear

Capture logs, check the last successful backup, and preserve the PostgreSQL and Beacon data volumes before destructive repair actions.