7
Troubleshooting
gsadmin edited this page 2026-08-10 11:43:31 +00:00

Troubleshooting

Symptom Check
Device never appears Agent log: bootstrap HTTP status; token not expired/consumed; ServerURL scheme is http/https (agent derives ws/wss)
/api/ready returns 503 Database reachable, NATS connected, NATS_ACCOUNT_SIGNING_SEED loaded
Browser shows "Offline" POST /api/messaging/credential succeeds; proxy preserves the WebSocket upgrade on /messaging/browser
Agent will not connect to NATS resolver.conf account matches NATS_ACCOUNT_*; WSS path reachable through the proxy
Install command fails only from the Win+R Run box (works in an open shell) The Run box launches Windows PowerShell 5.1 with -NoProfile, which defaults to TLS 1.0/1.1 and fails the handshake to a modern HTTPS edge. The generated command now sets TLS 1.2 first — re-copy it from Add device if you saved an older one
Install command / links show the proxy upstream name (e.g. https://executer_api/…) or the wrong host The proxy isn't forwarding the real Host/X-Forwarded-Host. In nginx, a location that sets any proxy_set_header drops all inherited ones — keep them at server{} level only (see the updated src/Infra/nginx sample). Definitive fix either way: set PUBLIC_SERVER_URL=https://your-host so the URL is pinned regardless of headers
Agent rejects the server certificate Self-signed servers auto-install the CA — confirm /api/enrollment/ca returns 200 and the agent could reach it; for a private/edge cert the agent didn't trust, set TlsSkipVerify=1 (registry/GPO, or configure --skip-tls-verify)
Remote shell won't open Remote shell is on by default; check the agent is online. It only stays off where AllowRemoteShell=0 was set (policy/registry). The shell page now reports non-response after 15s instead of hanging
Script "disabled by policy" AllowScriptExecution not set to 0 by GPO/registry
CSRF 403 The SPA sends X-CSRF-Token; ensure the csrf_token cookie is present
File delivery 503 S3_ENABLED=1 and S3 credentials/bucket configured
Job creation returns 409 Device is orphaned — push a new bootstrap token so the agent re-enrolls
Download "skipped" unexpectedly Local file already matches the supplied sha256, or S3 returned 304 for the stored ETag
docker compose pull fails Set REGISTRY in .env and run scripts/Initialize-GiteaSecrets.ps1 so CI has published images; deploy.sh falls back to building from source

Where the logs are

The server writes Serilog console output plus daily rolling files under LOG_PATH, size-capped and retained per role.

The agent logs under its ProgramData directory on Windows, or /var/lib/executer on unix. Agent.exe status prints machine- and human-readable state.