How to Fix WireGuard Handshake Failures (Troubleshooting Guide)

WireGuard’s handshake is the initial key exchange that has to succeed before any traffic can flow through the tunnel. When it fails, you get a connection that looks configured correctly but never actually passes data, and the error messages are usually unhelpful, just a “handshake did not complete” or nothing at all. Here’s how to work through the actual causes in the order they’re most likely to be the problem.

What the handshake actually does

WireGuard uses a cryptographic framework called Noise to establish a secure session between your device and the server before any real traffic moves. Both sides need to reach each other over UDP, verify each other’s public keys, and complete this exchange within a few seconds. If any part of that path is blocked, misconfigured, or mismatched, the handshake silently fails and retries on a loop rather than throwing a clear error, which is why diagnosing the cause takes some methodical checking rather than reading an obvious log message.

Step 1: Confirm the interface is actually up

Run sudo wg show on Linux, or check your app’s connection status on other platforms, to confirm the WireGuard interface is active at all. If the interface itself isn’t up, the problem is in your configuration file or app setup, not the network path, and the rest of this troubleshooting doesn’t apply yet. Fix any errors reported at this stage first.

Step 2: Check for a blocked UDP port

WireGuard runs over UDP, typically on port 51820 by default, though providers can use a different port. Some hotel, airport, corporate and campus networks block or heavily restrict outbound UDP traffic specifically, since UDP is less common for typical browsing and more associated with VPNs and gaming. Try switching to a mobile hotspot temporarily to rule this out: if the handshake completes instantly on a different network, the original network’s firewall is the actual problem, and no amount of config tweaking on your end fixes it. Some providers offer a TCP-based obfuscation option specifically for these restrictive networks, worth switching to if UDP is consistently blocked wherever you are.

Want to compare all VPNs side by side? Check our full VPN comparison table with scores across 18 criteria.

Step 3: Double-check your public and private keys

A mismatched key pair is one of the most common causes of a silent handshake failure, especially if you’re manually copying keys between a client config and a server config rather than using a provider’s app. Confirm the client’s PrivateKey corresponds to the public key the server has on file for you, and that the server’s public key in your client config matches what the server is actually presenting. A single extra space, a missing character, or an accidentally truncated key from a copy-paste error is enough to break the handshake with no other symptom.

Step 4: Verify the endpoint address and port

Your config’s Endpoint line needs the server’s correct current IP address (or hostname) and port. If a provider recently rotated server IPs, an old cached config pointing at a now-defunct address will fail silently rather than reporting a clear DNS or connection error. Re-downloading a fresh config file from your provider, rather than reusing an older saved one, resolves this in most cases.

Step 5: Add PersistentKeepalive if you’re behind NAT

If your device is behind a home router’s NAT, or worse, a mobile carrier’s CGNAT (carrier-grade NAT, common on mobile data connections), the server may lose the ability to reach you back after the initial handshake attempt, since your NAT’s mapping for that connection can time out from inactivity. Adding PersistentKeepalive = 25 to your client config’s peer section tells WireGuard to send a small keepalive packet every 25 seconds, keeping the NAT mapping open so the server can still reach you. This single line fixes a large share of “it connects, then drops” and intermittent handshake issues on mobile networks specifically.

Step 6: Review your AllowedIPs setting

The AllowedIPs field controls which traffic gets routed through the tunnel, and a misconfigured value here can create a routing loop that prevents the handshake packets themselves from reaching the right interface. If you’re troubleshooting rather than fine-tuning split tunneling, temporarily setting AllowedIPs = 0.0.0.0/0 (all traffic through the tunnel) rules out a routing-specific misconfiguration as the cause, and you can narrow it back down once the basic connection works.

Step 7: Lower the MTU if the handshake succeeds but traffic doesn’t flow

If wg show reports a successful, recent handshake but you still can’t load anything, an oversized MTU (maximum transmission unit) causing packet fragmentation is a common culprit, especially on connections with additional overhead like mobile data or certain ISP configurations. Try lowering the MTU in your config to 1280 or 1380 (down from WireGuard’s default of 1420) and reconnecting. This specific symptom, a successful handshake with no actual data flow, is one of the clearer signals pointing at MTU rather than the handshake process itself.

Step 8: Restart cleanly rather than reconnecting on top of a stuck session

Sometimes the fix genuinely is turning it off and on again, but doing it properly matters. Fully bring the interface down (sudo wg-quick down wg0) before bringing it back up, rather than trying to reconnect on top of a session WireGuard thinks is still active. A stuck kernel-level interface state, particularly after a laptop wakes from sleep, is a common and boring cause that a clean restart resolves without needing any of the deeper troubleshooting above.

When it’s a provider-side issue, not yours

If none of the above resolves it, and especially if the same config worked fine yesterday, check whether the specific server you’re connecting to is having an outage or maintenance window. Switching to a different server location through your provider’s app is a faster diagnostic step than continuing to troubleshoot a config that may be correct but pointed at a server that’s simply down. Most major providers post server status pages or support channels where this kind of outage gets acknowledged quickly. It’s a five-minute check that saves a lot of wasted time second-guessing a configuration file that was never actually the problem.

A quick checklist for next time

Keep this rough order in mind if it happens again: confirm the interface is up, rule out a blocked UDP port by testing on a different network, verify keys and endpoint address are current, add PersistentKeepalive if you’re on mobile data, and check AllowedIPs and MTU only if the earlier steps don’t resolve it. Working through causes in roughly this order, most common and quickest to check first, gets you to a fix faster than guessing at the more obscure possibilities before ruling out the simple ones.

Keep reading: WireGuard vs OpenVPN: Which Is Better? and How to Set Up a WireGuard VPN Server on Ubuntu Linux.