Skip to content

Troubleshooting

View as Markdown

Node-offline alert emails link here, so this heading stays put.

A node shows offline when it hasn’t checked in with the network for a few minutes. Most of the time the cause is on the machine running it and quick to fix.

  • The machine is asleep or powered off. Laptops and desktops sleep by default. Set the machine never to sleep while plugged in, or run the node on something that stays on.
  • The network changed. A new router, a different Wi-Fi network, a VPN or a firewall rule can stop the node reaching the network.
  • The service or container stopped. After an OS update, a reboot or a Docker update, check that it started again.
  • A container was recreated without its volumes. The node then enrolls as a brand new node, and the old one stays offline. See Node Appears as a New Node.

A node answers on port 8080 of the machine it runs on, unless you changed PORT or mapped the container to a different host port (such as 8081:8080); use that port instead. From that machine:

Terminal window
curl http://localhost:8080/health

A reply means the node is running. Then work through the steps for your install method below.

Command-line install (macOS, Linux, Windows)

Section titled “Command-line install (macOS, Linux, Windows)”
  • Status: ~/.ee-cdn/bin/edge-node status (on Windows, %USERPROFILE%\.ee-cdn\bin\edge-node.exe status).

  • Restart: ~/.ee-cdn/bin/edge-node stop, then ~/.ee-cdn/bin/edge-node start.

  • Logs: ~/.ee-cdn/logs/ (ee-cdn-edge-node.out.log and ee-cdn-edge-node.err.log):

    Terminal window
    tail -50 ~/.ee-cdn/logs/ee-cdn-edge-node.err.log
  • The service itself:

    • macOS: a launch agent at ~/Library/LaunchAgents/ee-cdn-edge-node.plist. launchctl list ee-cdn-edge-node shows whether it’s loaded.
    • Linux: a systemd unit named ee-cdn-edge-node. Run systemctl --user status ee-cdn-edge-node, or sudo systemctl status ee-cdn-edge-node if you installed as root. journalctl --user -u ee-cdn-edge-node (or sudo journalctl -u ee-cdn-edge-node) shows its output.
    • Windows: the EE-CDN Edge Node service, in the Services app.

This also covers NAS platforms that run the container: TrueNAS, Unraid, Portainer, Dockge, Umbrel and CasaOS.

  • Status: docker ps should list the container as Up. With Compose, run docker compose ps in the folder with docker-compose.yml.
  • Logs: docker logs --tail 50 <container>, or docker compose logs --tail 50 edge-node. NAS apps show the same output on the app’s Logs page.
  • Restart: docker restart <container>, or docker compose restart edge-node, or Restart in your NAS app.
  • Keep the node’s identity. With the Compose file, keep both volumes, edge-data (at /data) and edge-identity (at /var/lib/dbus). With a docker run install, keep the edge-data volume and the ~/edge-node-machine-id file mounted at /etc/machine-id (see Installation). If any of these is lost, the node enrolls as a new node.

From the machine (or inside the container with docker exec <container> wget -qO- https://cp.3dge.app/health):

Terminal window
curl -sSI https://cp.3dge.app/health

Any HTTP response means the network is reachable. A timeout or a DNS error points at the network, a firewall or a VPN.

Once the node is running and can reach cp.3dge.app, it shows online within a minute or two. If it doesn’t, post the last 50 lines of its log in our Discord or contact Node Support.

If your node shows in the portal as a new entry with no history, it enrolled with a different machine identity. The usual causes:

  • The operating system was reinstalled.
  • A container node was recreated without a fixed hostname and a persistent machine ID.
  • /etc/machine-id was removed or regenerated on Linux.

The previous node’s record still exists, and its Active Node Hours stopped at its last check-in. Your account balance and payouts are not affected.

If none of the above applies, contact us with both node names and the approximate date.

  • Check the goroutine count in the admin dashboard (Resources column)
  • Normal range: 15-30 goroutines and under 100 MB RAM
  • If you’re seeing more than 1,000 goroutines, restart the service
  • Your node needs at least one heartbeat cycle (30 seconds) to receive workload assignments
  • Check for cached files: ls ~/.ee-cdn/cache/workloads/
  • Make sure your allocated cache capacity isn’t full
  • Your node needs TURN credentials from the control plane, which arrive via the heartbeat
  • Check your logs for the message: Updated ICE config with TURN credentials
  • If you’re behind a strict corporate firewall, TURN on port 443 may be required