# Troubleshooting

> Fixes for common edge node problems: a node showing offline or reappearing as new, high memory use, content not caching, and WebRTC failures.

Source: https://docs.evolvingedge.ai/troubleshooting/

## 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

- **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](#node-appears-as-a-new-node).

### 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:

```sh
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)

- **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`):

  ```sh
  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.

#### Docker and Docker Compose

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](https://cp.3dge.app/docker-compose.yml), 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](https://docs.evolvingedge.ai/installation/)). If any of these is lost, the node enrolls as a new node.

### Check it can reach the network

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

```sh
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.

### 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](https://discord.gg/KUGFX9a4Xn) or contact [Node Support](https://docs.evolvingedge.ai/node-support/).

## 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-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](https://docs.evolvingedge.ai/node-support/) with both node names
and the approximate date.

## 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

- 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

- 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
