# Troubleshooting

> Diagnose installation, service, approval, connectivity and uninstall failures, with the E1xxx error-code table.

Source: https://www.widewired.com/page/docs/troubleshooting

## Collecting baseline state

Run on the affected device:

```
wwnet
```

Record the whole table — `status`, `network address`, the `peers` rows — plus the complete message and any `E1xxx` code. For a connectivity incident, collect the same output at both ends of the link.

If you already have a code, go directly to the [error-code table](#error-codes).

## Installation failures

| Message | Action |
| --- | --- |
| Root / Administrator rights required | Use `sudo` on Linux/macOS or an elevated PowerShell on Windows |
| Network ID malformed or not found | Copy the complete command again from **Configuration → Devices** |
| Intel Mac unsupported | macOS support is Apple Silicon only |
| `curl` missing | Install `curl` and retry |
| Signature or checksum failed | Do not bypass verification; retry on another network and contact support if persistent |

## Background service not running

`E1002` corresponds to `status` = `background service not running`. Inspect the service:

```
systemctl status wwnet            # Linux (systemd)
/etc/init.d/wwnet status          # OpenWrt
sudo launchctl list | grep wwnet  # macOS
Get-Service wwnet                 # Windows
```

A missing service usually means installation did not finish; rerun the install command. On Linux, use `journalctl -u wwnet -n 100 --no-pager`; on OpenWrt, use `logread | grep wwnet`.

`E1003` means the service is still initializing. Wait a few seconds and retry instead of restarting it repeatedly.

## Device remains pending

`status` = `awaiting approval` is the expected post-registration state. Approve the device under **Configuration → Devices** before testing connectivity.

If the device is absent from the list, registration did not complete. Return to the device and inspect the `wwnet` output and its error code.

## Two devices cannot communicate

Check in this order:

1. Both endpoints report `status connected` and are approved in the console.
2. The test target is the peer's `network address`, not a local-LAN address.
3. The overlay CIDR does not overlap either local LAN or a routed segment.
4. The target firewall permits ICMP or the actual application port on the virtual adapter.
5. The peer's `peers` row in `wwnet` shows a healthy path.
6. **Configuration → Links** has not disabled every available path.

If host policy blocks `ping`, test the real application port rather than treating ICMP alone as proof that the link is down.

## Relay used instead of direct

When direct traversal fails because of symmetric NAT, blocked UDP or strict outbound ACLs, selection falls back to peer relay or cloud relay. This is expected and preserves end-to-end encryption.

If the workload requires direct, inspect NAT type, outbound UDP and host firewalls on both sides. See [connectivity and paths](https://www.widewired.com/page/docs/paths).

## Cloud relay not active

Open the link under **Configuration → Links** and act on the displayed reason:

- **Credit initializing**: wait for sync; do not top up.
- **Credit exhausted**: cloud relay resumes after a settled top-up.
- **Schedule inactive**: check the plan, timezone and current time.
- **Region unknown / relay unavailable / account state**: wait for recovery or contact support.

## Network move conflicts

`E1042` means the installation already belongs to another network. Run:

```
wwnet leave
```

After it completes, use the new network's install command.

## Leave or uninstall incomplete

`E1060` corresponds to `status` = `needs attention`: routes, firewall state or the virtual adapter were not fully restored. Run:

```
wwnet uninstall
```

The command does not depend on the background service and is safe to repeat. Do not remove program directories or recovery data before it reports success.

## Windows security prompts

Windows or corporate endpoint protection may require approval on first download or execution. Follow organizational allow-list policy. If the installer reports a signature or SHA-256 failure, do not bypass it.

## Error codes

Client errors end with a stable code, for example:

```
wwnet: this command needs administrator/root privileges (E1001)
```

### Local action

| Code | Meaning | Action |
| --- | --- | --- |
| `E1001` | Insufficient privileges | Use `sudo` on Linux/macOS or an elevated PowerShell on Windows |
| `E1002` | Background service not running | Start it; on Linux use `sudo systemctl start wwnet` |
| `E1004` | Invalid command or arguments | Run `wwnet help` |
| `E1040` | Network not found | Copy the command from **Configuration → Devices** and confirm the network still exists |
| `E1041` | Operation conflicts with current state | Wait for the current join or cleanup to finish, then retry |
| `E1042` | Device already belongs to another network | Run `wwnet leave`, then join the new network |
| `E1050` | Request rejected by policy | Follow the message, for example freeing or raising the device limit |

### Wait or inspect the network

| Code | Meaning | Action |
| --- | --- | --- |
| `E1003` | Background service not ready | Wait a few seconds; do not restart it |
| `E1030` | WideWired services unreachable | Check internet access, proxy, DNS and outbound ACLs |
| `E1031` | Request rate limited | Wait before retrying and avoid a tight loop |

### Inspect the console

| Code | Meaning | Action |
| --- | --- | --- |
| `E1010` | Device identity no longer accepted | Confirm account, network and device are valid; reinstall if necessary |
| `E1011` | Two-factor authentication required | Complete verification in the console; see [account security](https://www.widewired.com/page/docs/account-security) |

### Contact support

| Code | Meaning | Action |
| --- | --- | --- |
| `E1020` | Server response could not be authenticated | Retry on another network; contact support if persistent, and do not bypass it |
| `E1060` | Leave or uninstall incomplete | Repeat `wwnet uninstall`; contact support if it persists |
| `E1000` | Unclassified error | Contact support with the `wwnet` output |

## Still unresolved

Contact support with the error code, occurrence time, OS version and the `wwnet` output from both endpoints; see [getting support](https://www.widewired.com/page/docs/support).