Docs

Troubleshooting

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

Collecting baseline state

First select the correct network and inspect Overview. For recent changes, compare Insights → Logs; for earlier connectivity problems, compare Insights → Transmission.

On Linux or Windows, 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.

On macOS and mobile devices, collect the app version, connection status, network ID and device information instead. The desktop command is not available in those apps.

Installation failures

Message	Action
Root / Administrator rights required	Use `sudo` on Linux or an elevated PowerShell on Windows
Network ID malformed or not found	Copy the complete command again from Configuration → Devices
`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
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 or firewall restrictions on the permitted UDP or TLS transport, selection falls back to In-Network Device Forwarding or Global Dedicated Transmission. This is expected and preserves end-to-end encryption.

If the workload requires direct, inspect NAT type, permitted direct transports and host firewalls on both sides. See Links.

Global Dedicated Transmission not active

Select the link in the Overview topology; under Path policy, the side panel shows why Global Dedicated Transmission is unavailable. Unplanned unavailability also appears under Insights → Alerts. Act on the displayed reason:

Credit state is initializing: wait for sync; do not top up.
Credit balance exhausted: Global Dedicated Transmission resumes after a settled top-up.
No Global Dedicated Transmission node is currently available: wait for recovery and use the free paths meanwhile; contact support if it persists.
Account is closed, Credit state conflict and other reasons: contact support.

Global Dedicated Transmission does not take part in path selection while it is turned off for the link or outside its working hours: under Configuration → Links, confirm that it is On for the link and check the working hours, timezone and current time.

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 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 the service	Copy the complete command again from Configuration → Devices and retry; contact support with the `wwnet` output if it persists

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; when it appears while registering a new device, approve or delete existing pending devices in the console first

Inspect the console

Code	Meaning	Action
`E1010`	Device identity no longer accepted	Confirm the account, network and device still exist, then follow the displayed recovery instructions

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.