Troubleshooting

import { Aside } from ‘@astrojs/starlight/components’;

This page collects the failures most people hit on their first deploy, ordered by how early they show up. Each entry has a symptom, a likely cause, and the command that confirms it.

Install

edgible agent install exits with “Permission denied”

Symptom: The install starts, then fails partway through with a permissions error on /etc/wireguard, iptables, or /etc/systemd.

Cause: The agent install needs root. The CLI checks at startup but a missing sudo further down can also surface this.

Confirm: Re-run with sudo:

sudo edgible agent install --type systemd --device-name my-first --non-interactive

“WireGuard is not available on this device”

Symptom: Install fails reporting that wg or wireguard-tools is missing.

Cause: WireGuard isn’t installed. Most modern kernels include it but userspace tooling is a separate package.

Confirm and fix:

which wg
# (if missing)
sudo apt install wireguard       # Debian/Ubuntu
sudo dnf install wireguard-tools # Fedora

Then re-run install.

Install hangs or times out

Symptom: edgible agent install runs for several minutes and never completes.

Cause: Outbound HTTPS to the control plane is blocked, so the device-creation API call hangs.

Confirm:

curl -sv https://api.v2.dev.edgible.com/healthz

If this hangs or 403s, your network is blocking the connection — check corporate proxies, firewall egress rules, or DNS resolution.

Connect

edgible device health reports the device as offline

Symptom: Install succeeded, agent started, but device health --name my-first returns offline or times out.

Cause: The agent isn’t reaching the control plane, or its credentials are wrong.

Confirm: Read the agent log:

sudo journalctl -u edgible-agent -n 200 --no-pager
# or
edgible agent logs --lines 200

Look for WebSocket connection failed or 401 Unauthorized. The first means a network problem; the second means the device credentials in ~/.local/share/edgible/config.json don’t match what the control plane has — try edgible config list to inspect.

Agent says “Organization not selected”

Symptom: Login worked but agent install complains about no organization.

Cause: Your account belongs to multiple organizations and none was auto-selected.

Fix:

edgible auth select-org
# or, directly:
edgible config set organizationId <org-id>

Deploy

stack deploy fails with “device not found”

Symptom: The deploy returns immediately with an error referencing the deviceName or deviceId from the YAML.

Cause: The selector in placement.deviceSelector doesn’t match any device in your organization.

Fix:

edgible device list

Confirm the spelling and that the device shows up. Update the YAML (or rename the device) and redeploy.

Status sticks at deploying indefinitely

Symptom: stack status stays in deploying for more than a minute or two.

Cause: The agent is taking a while to start the workload (large image pull, slow VM boot) or the workload is failing repeatedly.

Confirm: Pull the application’s events:

edgible application events --app-id <id> --limit 50
edgible device application-health --name <device>

A workload that fails to start will show up here with a reason (image pull failure, command not found, exit code).

Status sticks at deploying_gateway

Symptom: Workload is running but the application can’t reach ready.

Cause: Certificate issuance or HAProxy configuration on the gateway is taking longer than usual. For a custom domain, the most common cause is DNS not yet resolving to the gateway.

Confirm DNS for a custom domain:

dig <hostname> +short

The result should be the CNAME or A record stack status printed at deploy time. If not, DNS hasn’t propagated yet (wait) or the record is wrong (fix it). Once DNS resolves, validation completes within a minute or two.

Runtime

Hostname returns 502 Bad Gateway

Symptom: TLS handshake works, but the response is a 502.

Cause: Caddy on the serving device cannot reach the workload’s local port — usually because the workload crashed, isn’t bound to the right port, or is bound to 0.0.0.0 on a different interface.

Confirm on the device:

ss -lntp | grep <port>
# or
docker ps

Make sure something is listening on the containerPort you declared, on a loopback-reachable address. For Compose workloads, prefer 127.0.0.1:<port>:<port> over <port>:<port> to avoid race conditions with other interfaces.

Hostname returns 401 Unauthorized

Symptom: Requests to the hostname always return 401.

Cause: The access entry has an auth policy you may not have realized was set, and the request didn’t include a valid credential.

Confirm: Check the application’s auth mode:

edgible application get --app-id <id>

If it’s api-key, include Authorization: Bearer <token>. If it’s org, sign into Edgible in the same browser. If it’s short-code, check that the code hasn’t expired or been used up.

Connectivity test fails at TLS

Symptom: edgible connectivity test --host my-host --port 443 succeeds at DNS and TCP but fails at TLS.

Cause: The certificate hasn’t been issued yet (deploy is still in progress) or DNS resolves to the wrong target (the cert was issued for a different gateway than you’re hitting).

Confirm:

edgible stack status -f app.yml
dig <hostname> +short

stack status should show ready. The dig result should match the gateway target shown in the deploy output. If they don’t, fix the DNS record.

Cleanup

agent uninstall left WireGuard interfaces behind

Symptom: After uninstall, wg still shows interfaces, or ip link shows wg-edgible-*.

Cause: The uninstall path didn’t remove the WireGuard configuration cleanly.

Fix:

sudo wg-quick down wg-edgible-<pool>
sudo rm /etc/wireguard/wg-edgible-*

Then re-run agent uninstall --remove-files --force.

When to ask for help

If agent debug-dump --json > debug.json produces a file you can share, that file plus the application ID and approximate timestamp is what support will ask for first.