Tunnel won't come up — what to check
2 min · 4 steps
Common WireGuard bring-up failures + how to diagnose each.
The Test Connection button is the fastest path to a diagnostic. It tries each stage independently and tells you exactly which one failed.
Steps
- If endpoint is unreachable.
Your firewall or ISP is blocking the WireGuard UDP port (commonly 51820). Try Test Connection from a different network (tether off your phone) to confirm. If your IT team can SSH into the VPN box, ask them to confirm the UDP port is open in inbound rules.
- If endpoint is reachable but no handshake.
Almost always the keys are wrong (private key + server public key don't match the peer's expectation). Double-check the values from your IT team — base64 keys are 44 characters and end with =. Spaces / newlines from copy-paste are silent failure modes.
- If wg-quick errors with 'utun7 already exists'.
You have another WireGuard tunnel up (the official WireGuard.app, perhaps). Toggle it off there first, OR coexist — macOS assigns separate utun slots, but the error usually means a previous tunnel didn't clean up. Try `sudo wg-quick down utun7` in Terminal then retry.
- If you dismissed the password prompt by accident.
Just click the toggle again. There's no penalty — the auth cache resets when you cancel.
Live recipes need the desktop
This article is a static preview. The in-app Help sidecar inside Avery NXR can fire each step against your live project — install the desktop to use it interactively.