Troubleshooting
Node Shows Offline
Section titled “Node Shows Offline”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.
Common causes
Section titled “Common causes”- 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.
Check it’s running
Section titled “Check it’s running”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:
curl http://localhost:8080/healthA 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.logandee-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-nodeshows whether it’s loaded. - Linux: a systemd unit named
ee-cdn-edge-node. Runsystemctl --user status ee-cdn-edge-node, orsudo systemctl status ee-cdn-edge-nodeif you installed as root.journalctl --user -u ee-cdn-edge-node(orsudo journalctl -u ee-cdn-edge-node) shows its output. - Windows: the EE-CDN Edge Node service, in the Services app.
- macOS: a launch agent at
Docker and Docker Compose
Section titled “Docker and Docker Compose”This also covers NAS platforms that run the container: TrueNAS, Unraid, Portainer, Dockge, Umbrel and CasaOS.
- Status:
docker psshould list the container asUp. With Compose, rundocker compose psin the folder withdocker-compose.yml. - Logs:
docker logs --tail 50 <container>, ordocker compose logs --tail 50 edge-node. NAS apps show the same output on the app’s Logs page. - Restart:
docker restart <container>, ordocker 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) andedge-identity(at/var/lib/dbus). With adocker runinstall, keep theedge-datavolume and the~/edge-node-machine-idfile mounted at/etc/machine-id(see Installation). If any of these is lost, the node enrolls as a new node.
Check it can reach the network
Section titled “Check it can reach the network”From the machine (or inside the container with docker exec <container> wget -qO- https://cp.3dge.app/health):
curl -sSI https://cp.3dge.app/healthAny HTTP response means the network is reachable. A timeout or a DNS error points at the network, a firewall or a VPN.
Still offline?
Section titled “Still offline?”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.
Node Appears as a New Node
Section titled “Node Appears as a New Node”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-idwas 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.
High Memory Usage
Section titled “High Memory Usage”- 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
Content Not Cached
Section titled “Content Not Cached”- 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
WebRTC Connections Failing
Section titled “WebRTC Connections Failing”- 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
