Troubleshooting

Check the simplest layer that can explain the symptom, then move outward.

Process exits immediately

Run the same command in the foreground and read the fatal configuration error.
Check that every secret/certificate path exists and is readable by the service account, but not by unrelated users.
Run wgcloak --help and wgcloak check-config to spot a command or schema mismatch.
Confirm listener addresses are valid and no other process owns the port.

Client cannot connect

Verify DNS resolution and the configured server name/port.
Confirm the selected server listener is enabled and that the matching transport/port appears in its status output. In auto mode, check the configured client order and retry_ms status while it probes.
For direct UDP, check both directions in the host firewall and allow the server's UDP listener.
For TLS transports, verify the hostname matches the certificate and do not disable certificate verification.
Authentication rejection means a bad/unknown client or secret and must not be diagnosed as a firewall failure. Fix credentials before retrying.

Authentication failures or repeated probing

Check client ID spelling, secret-file contents, ownership/mode, and system clock skew. Direct HELLO timestamps have a target default 60-second window; replayed client nonces are rejected. Repeated invalid credentials should stop fallback probing rather than generate traffic across every transport.

Connected but no application traffic

Confirm the local application sends to the configured local UDP address.
Confirm the server backend is listening at [backend].target.
Check status/stats or structured logs for selected transport, maximum datagram size, dropped/oversized datagrams, and backend errors.
v1 remembers one most-recent local source peer per client tunnel. Concurrent source peers can replace that return destination and produce a warning.
No application-layer fragmentation exists: reduce payload size when the configured transport limit is exceeded (starting target is 1200 bytes).

Session disappears

The server's configured idle timeout applies per session. Check transport keepalive behavior, NAT expiry, server resource limits, and whether the client is reconnecting after a transport failure. A valid direct UDP packet can update the peer address after NAT rebinding; a spoofed packet without a valid MAC cannot.

Control socket unavailable

Check the daemon and CLI use the same XDG_RUNTIME_DIR, and verify the directory is private and the socket mode is 0600. If XDG_RUNTIME_DIR is unset or is not current-user-owned mode 0700, the daemon uses /run/user/<uid>/wgcloak/ when available, or $HOME/.local/run/wgcloak/. An active socket is never removed; a stale socket can be replaced only after its type and identity are checked. The reload command is present but currently returns an unsupported response; neither configuration nor certificate hot reload is implemented.

Host hardening prevents startup

Read the unit's journal output. Common causes are a secret/certificate path outside the unit's read paths, a changed binary location, or an address family not allowed by RestrictAddressFamilies. Correct the reviewed unit rather than weakening all hardening directives. CAP_NET_BIND_SERVICE is only needed for ports below 1024.

3.3 KiB Raw Blame History