Contents

Docs

Troubleshooting

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

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.

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:

Both endpoints report status connected and are approved in the console.
The test target is the peer's network address, not a local-LAN address.
The overlay CIDR does not overlap either local LAN or a routed segment.
The target firewall permits ICMP or the actual application port on the virtual adapter.
The peer's peers row in wwnet shows a healthy path.
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.

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

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.