Clone
7
Troubleshooting
gsadmin edited this page 2026-08-10 11:43:31 +00:00
Table of Contents
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.