When the tunnel will not connect

A handshake that never completes almost always has one of five causes.

WireGuard is quiet by design: when it fails it does not say why, it simply never completes a handshake. The causes are few, and this is the order worth checking them in.

1. Your connection is not reachable from outside

The most common cause of all, and it is not in your configuration. Many providers put customers behind shared IPv4, also called CGNAT: your router then has no address of its own on the internet, and nothing can open a connection towards it. Both ends can be correct and the tunnel will still never come up.

The fix is on the provider’s side — ask for a public IPv4 address, dynamic is enough, often cheap or free. IPv6, where offered, avoids the problem entirely.

2. The endpoint is wrong, or the port was never forwarded

Endpoint must be an address your device can reach from where it stands. Two frequent cases: the server sits behind a home router whose UDP port was never forwarded, or the address is dynamic and has since changed.

3. UDP is blocked on the network you are on

WireGuard runs over UDP, not TCP. Some hotel, airport, campus and corporate networks permit only ports 80 and 443 over TCP. Quick test: try the same connection over cellular. If it works there and fails on that Wi-Fi, the network is filtering and nothing in your configuration is wrong.

4. The keys do not match

Each side must hold the other’s public key. A hand-built configuration often ends up missing the server’s public key, or your own was never added on the server. The symptom is identical to a wrong endpoint: silence.

5. The clock is far off, or AllowedIPs is too narrow

WireGuard rejects handshakes whose timestamps look implausible — if your device’s date is badly wrong, set it back to automatic. And if the tunnel is up but the destination you want is not routed into it, nothing appears to happen: see DNS, routing and split tunnelling.

Still stuck

Send us what the app reports, what changed, and which network you are on — and please redact your private key first.