Troubleshooting

Common problems and their fixes. Each entry lists the symptom, the underlying cause, and the steps to resolve it.

1. Can ping one peer but not another, or no ping at all (kernel TUN)

Cause: The host is missing a route for the mesh address range, so the kernel does not send mesh-bound traffic to the blinex0 interface.

Fix: v0.9.5+ automatically adds the 100.64.0.0/10 route. If you are on an older agent or the route is missing, add it manually:

sudo ip route add 100.64.0.0/10 dev blinex0

2. LXC container can't ping out / agent stuck in netstack mode

Cause: Unprivileged LXC containers do not expose /dev/net/tun, so the agent falls back to netstack mode. Inbound connections work, but traffic originated by other apps on the host does not route into the mesh — the same trade-off as Tailscale's userspace mode.

Fix: Pass /dev/net/tun through from the Proxmox host by adding to /etc/pve/lxc/<CTID>.conf:

lxc.cgroup2.devices.allow: c 10:200 rwm
lxc.mount.entry: /dev/net/tun dev/net/tun none bind,create=file

then restart the container:

pct restart <CTID>

3. TOFU server certificate changed

Cause: The agent pins the control plane's self-signed certificate on first use (trust-on-first-use). If the certificate changes, the agent refuses to connect.

Fix: Clear the pinned state and restart the agent:

sudo rm /var/lib/blinex/state.json
sudo systemctl restart blinex-agent

Note:v0.10.3+ persists the server's self-signed certificate to a Docker volume (TLS_STATE_DIR), so restarting or rebuilding the control-plane containers no longer changes the fingerprint — this fix is typically only needed once.

4. Authentication handshake failed

Cause: The agent cannot verify the control plane's self-signed TLS certificate.

Fix: Set tls_skip_verify to true in /etc/blinex/agent.json:

{
  "tls_skip_verify": true
}

5. Dashboard shows "cannot reach management server"

Cause: The dashboard cannot verify the management server's self-signed certificate.

Fix: Set MGMT_TLS_SKIP_VERIFY=truein the dashboard's environment, then recreate the container (a plain restart will not pick up the new env var):

docker compose down dashboard
docker compose up -d dashboard

6. docker compose: "variable is not set"

Cause: The required environment file is missing, so Compose has no values for the referenced variables.

Fix: Copy the example env file and fill in the secrets:

cp .env.example .env
# set JWT_SECRET, POSTGRES_PASSWORD,
#     BLINEX_DEFAULT_KEY, RELAY_AUTH_PASS

7. Peers show "not connected" in the dashboard

Cause: Older management builds did not derive peer status from active sync streams.

Fix: Fixed in v0.10.1 (status is now reported from active sync streams). Ensure your management server is v0.10.1 or newer.

8. Can't delete a peer, or it reappears after deletion

Cause: base64 WireGuard keys containing a / broke the delete route at both the gin router and the dashboard proxy. Separately, a still-running agent with a valid setup key can simply re-enroll itself.

Fix: The routing bug is fixed in v0.10.2 and v0.10.6 — ensure both management and dashboard are v0.10.6 or newer. To remove a device permanently, also stop and uninstall the agent so it cannot re-enroll. Note that deleting a peer requires an Admin login; a device-token session cannot delete.

9. Direct ICE path is not engaging (peers stay on relay)

Cause: When both ends sit behind NATs that block hole-punching, ICE cannot establish a direct path, so peers remain on the relay. This is expected and harmless — relay always works and is just as encrypted.

Fix: Check the PATH column of blinex-agent peers to see which peers are direct vs relayed. To improve the odds of a direct path, ensure inbound UDP 49152-49252 and UDP 3478 (TURN) are open on the server.