Error codes (EDG)
Every install, preflight, edgible doctor, and self-update failure line carries a stable EDG### code. Search this page for the code in your output — each entry says what happened, why, and the exact command to fix it.
| Range | Area |
|---|---|
| 1xx | Environment and dependencies on the local host |
| 2xx | Network, platform reachability, and credentials |
| 3xx | Agent first-connect stages (after the service starts) |
| 4xx | Artifact distribution and install operations |
| 5xx | CLI self-update |
| 6xx | Uninstall |
EDG100 — Unsupported operating system or architecture
Section titled “EDG100 — Unsupported operating system or architecture”What happened: The installer refused to run on this platform.
Why: Edgible supports Linux and macOS on x86_64 and arm64. Windows is not yet supported.
Fix: Re-run the install on a supported host. Check yours with uname -sm.
EDG101 — Target directory not writable
Section titled “EDG101 — Target directory not writable”What happened: The install could not create or write to its target directory.
Why: The chosen prefix (e.g. /opt/edgible-cli or the agent config dir) needs privileges this user doesn’t have.
Fix: Re-run with sudo, or point the install at a user-writable path (EDGIBLE_CLI_PREFIX=$HOME/.edgible/cli for the CLI installer).
Related: EDG502
EDG102 — Daemon controller missing
Section titled “EDG102 — Daemon controller missing”What happened: The service manager the install method needs (systemctl, launchctl, …) is not available.
Why: This host doesn’t run the init system the chosen install type manages the agent with — commonly a minimal container image without systemd.
Fix: Install on a host running the expected init system, or use --type foreground to run the agent without a daemon manager.
Related: EDG122
EDG103 — Node.js runtime problem
Section titled “EDG103 — Node.js runtime problem”What happened: Node.js is missing, older than 20, or sits at an unstable path (e.g. an npx temp dir the daemon unit would hard-code).
Why: The CLI, SDK, and agent all require Node.js 20+ at a stable path.
Fix: Install Node 20+ and re-run — brew install node (macOS), curl -fsSL https://deb.nodesource.com/setup_20.x | sudo bash - && sudo apt-get install -y nodejs (Debian/Ubuntu), or nvm install 20. The CLI installer can do this for you (EDGIBLE_INSTALL_NODE=1).
EDG104 — Low free disk space
Section titled “EDG104 — Low free disk space”What happened: The target filesystem has less free space than the install needs (~500MB for the CLI bundle, ~300MB–1GB for the agent).
Why: The unpacked bundle includes its vendored node_modules.
Fix: Free up space on the target filesystem (df -h <target> shows usage) and re-run.
EDG105 — curl not installed
Section titled “EDG105 — curl not installed”What happened: The installer needs curl to download artifacts and it’s not on PATH.
Fix: sudo apt-get install -y curl (or your distro’s equivalent), then re-run.
Related: EDG106
EDG106 — unzip not installed
Section titled “EDG106 — unzip not installed”What happened: The installer needs unzip to extract the bundle and it’s not on PATH.
Fix: sudo apt-get install -y unzip (or your distro’s equivalent), then re-run.
Related: EDG105
EDG110 — WireGuard tools not installed
Section titled “EDG110 — WireGuard tools not installed”What happened: The wg binary is missing.
Why: The agent manages device-pool tunnels with the WireGuard userspace tools.
Fix: sudo apt-get install -y wireguard (Debian/Ubuntu), dnf install -y wireguard-tools (Fedora), or brew install wireguard-tools (macOS). edgible agent install can install it for you when you accept the prompt.
EDG111 — Caddy not installed (serving device)
Section titled “EDG111 — Caddy not installed (serving device)”What happened: The caddy binary is missing on a serving device.
Why: Serving devices terminate TLS for workloads with Caddy.
Fix: sudo apt-get install -y caddy (or brew install caddy). On Alpine, enable the community repository in /etc/apk/repositories first.
EDG112 — HAProxy not installed (gateway device)
Section titled “EDG112 — HAProxy not installed (gateway device)”What happened: The haproxy binary is missing on a gateway device.
Why: Gateways route inbound traffic to serving devices through HAProxy.
Fix: sudo apt-get install -y haproxy (or your distro’s equivalent), then re-run the install.
EDG113 — iptables not installed
Section titled “EDG113 — iptables not installed”What happened: The iptables binary is missing.
Why: The agent programs NAT/forwarding rules for the WireGuard data path.
Fix: sudo apt-get install -y iptables (or your distro’s equivalent), then re-run.
EDG114 — wireguard-go not installed
Section titled “EDG114 — wireguard-go not installed”What happened: The userspace WireGuard implementation is missing on a host that needs it.
Why: When the kernel module can’t be used (macOS, some containers/kernels), the agent falls back to wireguard-go.
Fix: brew install wireguard-go (macOS) or install wireguard-go from your package manager, then re-run.
EDG120 — WireGuard kernel module not loadable
Section titled “EDG120 — WireGuard kernel module not loadable”What happened: /sys/module/wireguard is absent and modprobe -n wireguard failed. If wireguard-go is present this is a warning (userspace mode, reduced throughput); without it the agent cannot bring up tunnels.
Why: The kernel lacks the module, or headers don’t match the running kernel.
Fix: sudo apt-get install wireguard (Debian/Ubuntu) or install kernel headers matching uname -r; alternatively install wireguard-go for userspace mode.
EDG121 — IPv4 forwarding disabled (gateway device)
Section titled “EDG121 — IPv4 forwarding disabled (gateway device)”What happened: /proc/sys/net/ipv4/ip_forward is 0.
Why: A gateway cannot route traffic to serving devices without IP forwarding.
Fix: sudo sysctl -w net.ipv4.ip_forward=1 && echo 'net.ipv4.ip_forward=1' | sudo tee -a /etc/sysctl.conf. The gateway installer enables this during WireGuard setup.
EDG122 — Container without a working systemd
Section titled “EDG122 — Container without a working systemd”What happened: This looks like a container, and systemctl is-system-running reports systemd is not functional.
Why: The systemd install method can’t manage the agent without a working systemd init.
Fix: Re-run the install with --type foreground, or run the container with a systemd init.
Related: EDG102
EDG123 — Docker not installed
Section titled “EDG123 — Docker not installed”What happened: docker --version failed on a serving device (warning — the agent still installs).
Why: Docker and Compose workloads deployed to this device will fail until Docker is present.
Fix: Install Docker (https://docs.docker.com/engine/install/), then sudo systemctl enable --now docker.
EDG130 — Port 51820/udp already in use
Section titled “EDG130 — Port 51820/udp already in use”What happened: Another process holds WireGuard’s tunnel endpoint port.
Fix: Inspect with sudo ss -lunp 'sport = :51820', then stop or reconfigure the conflicting service (e.g. sudo systemctl disable --now <service>). A port held by the agent’s own stack is fine and passes automatically.
EDG131 — Port 80/tcp already in use
Section titled “EDG131 — Port 80/tcp already in use”What happened: Another process holds port 80, which the agent needs for HTTP ingress (ACME challenges and redirects).
Fix: Inspect with sudo ss -ltnp 'sport = :80', then stop or reconfigure the conflicting service (commonly nginx or Apache: sudo systemctl disable --now nginx).
EDG132 — Port 443/tcp already in use
Section titled “EDG132 — Port 443/tcp already in use”What happened: Another process holds port 443, which the agent needs for HTTPS ingress.
Fix: Inspect with sudo ss -ltnp 'sport = :443', then stop or reconfigure the conflicting service.
EDG200 — DNS resolution failed
Section titled “EDG200 — DNS resolution failed”What happened: The hostname of the download or API endpoint would not resolve.
Fix: Check this machine’s DNS (resolvectl status), and any VPN or proxy that rewrites DNS. If you overrode the endpoint (EDGIBLE_CLI_BASE_URL, EDGIBLE_DISTRIBUTION_URL), verify the value.
Related: EDG201
EDG201 — Connection failed (network or proxy)
Section titled “EDG201 — Connection failed (network or proxy)”What happened: A download or connection attempt failed outright, or returned an unexpected HTTP status.
Fix: Check outbound HTTPS (443) connectivity and any HTTP proxy settings, then retry. If it persists, report it — the distribution channel may be misconfigured.
Related: EDG200, EDG204, EDG205
EDG202 — Download endpoint returned HTTP 403
Section titled “EDG202 — Download endpoint returned HTTP 403”What happened: The distribution endpoint denied access to a release artifact.
Why: Either the artifact was never deployed or the distribution (CloudFront/S3) is misconfigured — this is a problem on Edgible’s side, not yours.
Fix: Please report it, including the URL from the error output.
Related: EDG203
EDG203 — Download endpoint returned HTTP 404
Section titled “EDG203 — Download endpoint returned HTTP 404”What happened: The requested release manifest or bundle does not exist on the channel.
Why: Usually a pinned version that was never published.
Fix: Check EDGIBLE_CLI_VERSION / EDGIBLE_AGENT_VERSION and the base URL; omit them to install the latest release.
EDG204 — Network request timed out
Section titled “EDG204 — Network request timed out”What happened: The endpoint did not respond within the timeout.
Fix: Check connectivity and firewall rules for outbound HTTPS (443), then retry.
Related: EDG201
EDG205 — TLS handshake failed
Section titled “EDG205 — TLS handshake failed”What happened: curl could not complete a TLS handshake with the endpoint.
Why: Usually a proxy intercepting TLS, missing/stale CA certificates, or a badly skewed system clock.
Fix: Ensure ca-certificates is installed and current, check the system clock, and check for TLS-intercepting proxies.
Related: EDG211
EDG210 — Edgible API unreachable
Section titled “EDG210 — Edgible API unreachable”What happened: The Edgible API did not answer at all (any HTTP response, even an error status, counts as reachable).
Fix: Check outbound HTTPS (443) from this host to the API host, and any proxy/firewall egress rules.
Related: EDG304
EDG211 — Host clock skewed against the Edgible API
Section titled “EDG211 — Host clock skewed against the Edgible API”What happened: This host’s clock is significantly off from the API’s (over ~30s warns, over ~120s fails).
Why: Skew breaks request signing, device authentication, and TLS validation.
Fix: sudo timedatectl set-ntp true (or sudo chronyc makestep), then re-run.
EDG220 — CLI session token missing or expired
Section titled “EDG220 — CLI session token missing or expired”What happened: No Edgible session token was found on this machine, or it has expired.
Fix: Run edgible auth login.
Related: EDG221
EDG221 — Device credentials rejected
Section titled “EDG221 — Device credentials rejected”What happened: The device ID/password this host presented were rejected by the platform.
Fix: Re-enroll with fresh credentials (edgible agent enroll) and verify the host clock is in sync — a skewed clock fails auth the same way.
Related: EDG220, EDG303, EDG211
EDG301 — Agent service failed to start
Section titled “EDG301 — Agent service failed to start”What happened: The agent service is not running — it failed to start or crashed immediately.
Fix: Inspect the crash: journalctl -u edgible-agent -n 100 or edgible agent logs. The diagnostics file written next to the install output captures the same evidence.
Related: EDG302
EDG302 — Agent started but never wrote its status file
Section titled “EDG302 — Agent started but never wrote its status file”What happened: The agent process started but crashed before finishing initialization (no status.json within the wait window).
Fix: Check edgible agent logs (or the service’s stderr.log) for the first error after startup, and re-run edgible doctor.
Related: EDG301
EDG303 — Device authentication rejected by the backend
Section titled “EDG303 — Device authentication rejected by the backend”What happened: The agent started, but the backend rejected this device’s credentials.
Fix: Re-check EDGIBLE_DEVICE_ID/EDGIBLE_DEVICE_PASSWORD (or re-run edgible agent enroll with fresh credentials) and verify the host clock is in sync (sudo timedatectl set-ntp true) — see EDG211.
EDG304 — WebSocket control channel unreachable
Section titled “EDG304 — WebSocket control channel unreachable”What happened: The device authenticated, but its WebSocket control channel to the backend never connected.
Fix: Allow outbound HTTPS (443) to the Edgible API/WebSocket host from this device — corporate proxies and egress firewalls are the usual cause.
Related: EDG210
EDG305 — Agent healthy locally but backend never saw it online
Section titled “EDG305 — Agent healthy locally but backend never saw it online”What happened: Everything looks healthy on the device, but the backend never reported it online within the wait window.
Fix: Give it a minute and check edgible device list. If it stays offline, run edgible doctor and contact support with the diagnostics file.
Related: EDG310
EDG306 — WireGuard handshake absent or stale
Section titled “EDG306 — WireGuard handshake absent or stale”What happened: The control plane is up, but no WireGuard peer handshake completed — the data tunnel is dead.
Fix: Allow outbound UDP 51820. If the gateway and this device sit behind the same NAT, the router likely lacks hairpin support — see the troubleshooting guide for workarounds.
EDG310 — Backend verification skipped (no API connectivity from this machine)
Section titled “EDG310 — Backend verification skipped (no API connectivity from this machine)”What happened: The install verified locally, but the machine running the CLI could not reach the Edgible API to confirm the device is visible. This is a warning, not a failure.
Fix: Run edgible device list from a machine with API access, or edgible doctor here once connectivity returns.
EDG401 — Release manifest missing or invalid
Section titled “EDG401 — Release manifest missing or invalid”What happened: The channel’s release manifest (<version>.json) could not be fetched, or is missing required fields (version, sha256). When a signing key is baked in, installs fail closed rather than proceed unverified.
Fix: Check EDGIBLE_CLI_BASE_URL / EDGIBLE_AGENT_VERSION; omit them to install the latest release. If unchanged defaults fail, report it.
EDG402 — Bundle sha256 checksum mismatch
Section titled “EDG402 — Bundle sha256 checksum mismatch”What happened: The downloaded bundle’s checksum did not match the release manifest. Nothing was installed — an existing install is untouched.
Why: The download is corrupt or has been tampered with.
Fix: Retry the install. If it persists, report it — do not bypass the check.
Related: EDG403
EDG403 — Manifest signature verification failed
Section titled “EDG403 — Manifest signature verification failed”What happened: The release manifest’s signature did not verify against the baked-in signing key (or the manifest was unsigned while a key was pinned). The install refused to proceed.
Fix: Retry once (a partially propagated release can race). If it persists, report it immediately — do not work around a signature failure.
EDG404 — Bundle entry point missing after extraction
Section titled “EDG404 — Bundle entry point missing after extraction”What happened: The bundle extracted, but its entry point (dist/index.js or the vendored SDK) is missing — a bad artifact. The installer refused to activate it.
Fix: Re-run the install to fetch a fresh copy. A previous version (if any) is still under <prefix>/versions — re-point <prefix>/current at it to roll back manually.
EDG405 — Bundle extraction failed
Section titled “EDG405 — Bundle extraction failed”What happened: unzip failed while extracting the downloaded bundle.
Fix: Check free disk space at the install prefix and that unzip works, then re-run the installer.
EDG406 — Atomic symlink swap failed
Section titled “EDG406 — Atomic symlink swap failed”What happened: The new version unpacked, but the installer could not swap the current symlink to activate it. The previous install keeps working.
Fix: Check permissions and filesystem state at <prefix>/current, then re-run the installer.
EDG407 — Launcher write failed
Section titled “EDG407 — Launcher write failed”What happened: The installer could not write the edgible launcher into the bin directory.
Fix: Check the bin dir is writable (/usr/local/bin system-wide, ~/.local/bin user), or set EDGIBLE_CLI_BIN_DIR to a writable directory and re-run.
EDG410 — Agent file provisioning failed
Section titled “EDG410 — Agent file provisioning failed”What happened: Writing the agent’s files (bundle, config directory contents) onto the host failed.
Fix: Check disk space and permissions on the agent config directory, then re-run the install with sudo.
EDG411 — Agent config invalid after write
Section titled “EDG411 — Agent config invalid after write”What happened: The agent configuration failed validation immediately after being written.
Fix: Re-run the install (it rewrites the config from your inputs). If it persists, report it with the install output.
Related: EDG410
EDG412 — Daemon unit install failed
Section titled “EDG412 — Daemon unit install failed”What happened: Installing or reloading the agent’s service unit (e.g. the systemd unit) failed.
Fix: Re-run with sudo, then check systemctl daemon-reload and journalctl -u edgible-agent for the underlying error.
EDG500 — No install manifest (dev checkout or legacy install layout)
Section titled “EDG500 — No install manifest (dev checkout or legacy install layout)”What happened: edgible upgrade (or edgible uninstall) could not find install-manifest.json, so this CLI was not installed by the installer.
Fix: Reinstall with curl -fsSL https://get.edgible.com/install.sh | bash — subsequent upgrades will then work in place. Dev checkouts update via git pull, not upgrade.
Related: EDG501
EDG501 — Could not fetch the latest-version manifest
Section titled “EDG501 — Could not fetch the latest-version manifest”What happened: edgible upgrade could not fetch or parse the release channel’s version manifest.
Fix: Check outbound HTTPS (443) to get.edgible.com and retry. If your install uses a custom channel, verify its base URL in <prefix>/install-manifest.json.
EDG502 — Install prefix not writable for upgrade
Section titled “EDG502 — Install prefix not writable for upgrade”What happened: This CLI was installed system-wide and the current user cannot write the install prefix or launcher dir.
Fix: Re-run with elevated privileges — edgible upgrade prints the exact sudo env EDGIBLE_CLI_VERSION=… bash -c "curl … | bash" command to copy-paste.
EDG600 — Nothing to uninstall
Section titled “EDG600 — Nothing to uninstall”What happened: The uninstaller found no install at the expected prefix and no launcher.
Fix: If you installed to a custom location, set EDGIBLE_CLI_PREFIX / EDGIBLE_CLI_BIN_DIR to match and re-run. For non-interactive removal, add --yes: curl -fsSL https://get.edgible.com/install.sh | bash -s -- --uninstall --yes.
Related: EDG500