Edge supervisor won’t start

You’re on the edge box. systemctl status wiqaia-edge-supervisor shows the unit failing, or the on-box dashboard (http://<edge-host>:8081) is unreachable.

Work through this top-to-bottom; each step ends with how to confirm the issue is fixed before moving on.

0. Confirm the symptom

sudo systemctl status wiqaia-edge-supervisor
sudo journalctl -u wiqaia-edge-supervisor -n 100 --no-pager

Whatever’s wrong, the journal output narrows it down. Common patterns below.

1. “exec /usr/local/bin/wiqaia-edge-supervisor: no such file or directory”

The bootstrap didn’t finish, or the binary was deleted.

ls -la /usr/local/bin/wiqaia-edge-supervisor

Fix: re-run the bootstrap installer (it’s idempotent — successful steps no-op):

sudo /usr/local/bin/wiqaia-bootstrap-install.sh 
    --token <one-time-token> 
    --building-id <uuid>

If you don’t have a token, generate a fresh one in the cloud admin UI. The bootstrap will detect the existing keypair + reuse it (no re-registration needed).

2. “config load failed; running in degraded mode (healthz only)”

The supervisor IS running but couldn’t read /etc/wiqaia/edge.yaml. The journal will say path=/etc/wiqaia/edge.yaml err=....

sudo cat /etc/wiqaia/edge.yaml
sudo -u wiqaia-edge stat /etc/wiqaia/edge.yaml   # confirm the supervisor user can read it

Common cases:

  • File doesn’t exist — bootstrap didn’t reach step 7b. Re-run it.
  • YAML parse error — somebody hand-edited the file. Don’t. Re-run bootstrap to regenerate.
  • gateway_id is the placeholder 00000000-... — the bootstrap step register_with_fleet failed silently (older version, or fleet API was unreachable at registration time). Re-run bootstrap.
  • Permission denied — the file isn’t readable by the wiqaia-edge user. Run sudo chown wiqaia-edge:wiqaia-edge /etc/wiqaia/edge.yaml and try again.

Confirm the fix:

sudo systemctl restart wiqaia-edge-supervisor
wiqaia-edge status    # should show gateway id + ✓ online

3. “tunnel dial failed” repeating in logs

The supervisor’s running and configured, but can’t reach the fleet manager.

# Are we reaching the API at all?
curl -fsS https://api.wiqaia.sa/healthz

# DNS?
nslookup edge.wiqaia.sa

# What does the supervisor's config say?
sudo grep fleet_endpoint /etc/wiqaia/edge.yaml

Common cases:

  • Customer firewall blocking outbound 443 — call the network team. Get the IP whitelist exception. The supervisor uses HTTPS, not the legacy 51820 UDP we used in early dev.
  • fleet_endpoint typo’d — re-run bootstrap with the correct --fleet-manager-url flag.
  • mTLS cert rejected — the cloud’s edge_gateway.certificate_fingerprint doesn’t match what the supervisor’s presenting. Re-run bootstrap; it regenerates the cert + posts the fresh fingerprint.

The supervisor retries forever with exponential backoff (1 s → 2 → 4 → … → 60 s); a transient outage will self-heal once the network’s back.

4. “permission denied” on docker.sock

The supervisor needs to manage Docker containers. The systemd unit adds it to the docker group via SupplementaryGroups=docker.

groups wiqaia-edge      # should include 'docker'
ls -la /var/run/docker.sock

If the docker group is missing:

sudo gpasswd -a wiqaia-edge docker
sudo systemctl restart wiqaia-edge-supervisor

5. systemd crash-loop limit reached

The unit’s StartLimitBurst=5 over StartLimitIntervalSec=300 means 5 failures in 5 minutes blocks further restarts. Operator override:

sudo systemctl reset-failed wiqaia-edge-supervisor
sudo systemctl start wiqaia-edge-supervisor

If it crash-loops again, stop touching it — get the journal first:

sudo journalctl -u wiqaia-edge-supervisor -n 200 --no-pager > /tmp/supervisor.log

…and post that to the team channel before more restarts.

Last resort: full reinstall

If nothing above worked, the bootstrap script is idempotent and safe to re-run:

# Get a fresh enrollment token in the admin UI; existing cert keeps its
# identity unless explicitly rotated.
sudo /usr/local/bin/wiqaia-bootstrap-install.sh 
    --token <token> 
    --building-id <uuid>

Don’t blow away /var/lib/wiqaia/ first — the existing keypair + queue state should survive.

WiqAIa+ Docs · Rizoma