WireGuard Handshake Did Not Complete: Checks and Fixes

A stalled WireGuard handshake is one of the most common VPN headaches, and the fix almost never involves touching encryption settings. The wireguard handshake is a two-message exchange: your device sends an initiation, the server answers, and both sides generate session keys. When that exchange never finishes, the cause is nearly always reachability or a configuration mismatch, not a problem with WireGuard itself.

A missing handshake points to one of four things: a blocked UDP path, a mismatched key or preshared key, a stale endpoint, or a NAT mapping that closed. Each has a distinct, reversible test, and working through them in order usually finds the culprit in a few minutes. We built VPNSoEasy around a simpler path: the VPNClient app connects through a dashboard login instead of hand-edited configs, which removes most of the mistakes described below. If your own setup is stuck on an incomplete handshake, this guide walks through the checks that actually isolate the cause.

Is the Handshake Actually Failing?

Before changing anything, confirm whether the wireguard handshake has ever succeeded or just gone quiet. The command wg show tells you which situation you’re in, and that distinction changes where you look next.

What Does the Five-Second Retry Message Mean?

“Handshake did not complete after 5 seconds, retrying” is WireGuard’s built-in retry timer, not a setting you can adjust. The client sent an initiation and got no valid response in that window, so it tries again. WireGuard keeps retrying for about 90 seconds total before giving up, and each retry is a fresh signal that the response path, not just the request path, is broken somewhere.

Read Endpoint, Latest Handshake, and Transfer Fields with wg show

Run wg show on the client and look at three fields together. endpoint confirms where your device thinks the server is; latest handshake tells you if one has ever completed; transfer shows whether any bytes have moved in either direction. A blank latest handshake means no handshake has ever succeeded on this interface, which usually points to configuration or a blocked path rather than a network that briefly dropped out.

Generate Tunnel Traffic Before Treating an Old Handshake as a Failure

An old but nonzero handshake timestamp is a different problem than a blank one. WireGuard stays silent when there’s nothing to send, so a quiet tunnel can look dead even when it isn’t. Ping something across the tunnel or open a page first; if the handshake timestamp updates and transfer counters move, the tunnel was fine and just idle.

Check the Endpoint, Keys, Firewall, and NAT

Most non-starting handshakes trace back to one of four checks: the address the client is trying to reach, whether both sides hold matching keys, whether udp port 51820 is actually open along the path, and whether a NAT mapping has gone stale. Working through these in order avoids chasing the wrong fix.

Verify the Endpoint Address, DNS Resolution, and Listening Port

The Endpoint field is resolved once, at interface startup, so a hostname pointing to an address that changed since then sends your initiations nowhere. Confirm the hostname resolves to the server’s current public IP, and that the port in Endpoint matches the server’s ListenPort. Bringing the interface down and back up forces a fresh DNS lookup, which is often enough if the server’s address changed.

Compare Peer Public Keys and Check Preshared-Key Settings

A single mismatched character in a public key breaks the handshake, and the server stays silent rather than revealing anything about the failure. Run wg show on both sides and compare the public key each side has on file for the other. If a preshared key is set on one peer and missing on the other, the result looks identical: the initiation is sent, nothing comes back.

Trace UDP Through Host Firewalls, Router Rules, and Cloud Security Rules

WireGuard is UDP-only with no TCP fallback, so any network that blocks outbound UDP silently drops the handshake with no error at all. Check the host firewall for an inbound allow rule on udp port 51820, confirm the router forwards that port to the right LAN address if the server sits behind one, and check cloud security group rules if the server runs on AWS, Azure, or Google Cloud. Hotel, campus, and corporate Wi-Fi networks block UDP routinely, which is why a config that works at home can fail entirely somewhere else; if you travel a lot, it’s worth reading how a VPN interacts with Starlink connections or other non-standard networks before assuming your config is broken.

Identify Double NAT, CGNAT, and Idle NAT Mappings

A NAT mapping that closes from inactivity looks exactly like a dead handshake, because the server’s reply has nowhere to land once the mapping expires. Setting persistentkeepalive = 25 on the peer behind NAT keeps the mapping open by sending a small packet every 25 seconds. Double NAT or carrier-grade NAT (CGNAT) on the client side can block inbound replies entirely regardless of keepalive settings, which is one reason a connection that worked on one network drops consistently on another, something covered in more detail in our notes on a VPN that keeps disconnecting.

What if the Handshake Works but Internet Access Does Not?

A completed wireguard handshake with no browsing access is a routing problem, not a connection problem. The session keys are valid and wg show reports a recent handshake, so the fix lives in allowed ips, forwarding, or DNS rather than anything cryptographic.

Check AllowedIPs, Tunnel Addresses, and Conflicting Routes

AllowedIPs acts as both a routing rule and a peer selector, so a value that’s too narrow, too broad, or pointed at the wrong subnet breaks traffic while leaving the handshake intact. For full-tunnel setups, 0.0.0.0/0 and ::/0 are the common values; for split tunneling, list only the specific subnets meant to travel through WireGuard. Subnet overlap between the client’s local network and the server’s LAN (both using 192.168.1.0/24, for instance) sends packets to the wrong gateway and looks like a dead tunnel even though the handshake succeeded.

Verify IP Forwarding, Forwarding Rules, and Outbound NAT

A WireGuard server needs ip forwarding enabled to pass packets between the tunnel interface and the outside network. On Linux, that means /proc/sys/net/ipv4/ip_forward set to 1, saved in /etc/sysctl.conf so it survives a reboot. Client traffic exiting through the server’s public interface also needs outbound NAT masquerading configured, or packets reach the server and stop there.

Separate DNS Failures from MTU and Application Problems

If sites don’t load but the tunnel is connected and forwarding is correct, test with a raw IP address before blaming the tunnel. A page that loads by IP but not by domain name is a DNS issue, not a WireGuard issue. A path that handles small packets fine but stalls on larger transfers points to an MTU mismatch rather than anything in the WireGuard configuration itself, and this difference matters when picking a Chromebook WireGuard setup where MTU defaults vary by platform.

Restore Your VPNSoEasy Connection Without Manual Configuration

A VPNSoEasy connection that won’t establish is fixed through the VPNClient app and dashboard, not through editing any WireGuard config file. VPNSoEasy doesn’t offer configuration-file downloads, so none of the key-matching or endpoint-editing steps above apply to our setup; the fixes live in the app itself.

Use VPNClient and the VPN Credentials in Your Dashboard

Open the “Download the VPN App” section of your VPNSoEasy dashboard, install VPNClient, and sign in with the VPN username and password shown in the dashboard’s “Your VPN” card, which is separate from your website login. Mixing up those two logins is the most common reason a connection attempt fails outright before it even reaches a server.

Reconnect, Try Another Server, and Compare Networks

Disconnecting and reconnecting inside VPNClient re-establishes the session cleanly, much like bringing a WireGuard interface down and up. If one server location won’t connect, switching to another through VPNClient rules out a single server being the problem; the server network page shows current load for each location. Testing on a mobile hotspot versus your regular Wi-Fi also tells you quickly whether the local network is filtering VPN traffic, a pattern worth comparing against our guide on cheap WireGuard VPN providers if you’re evaluating network-friendliness across services.

Contact Support with Useful Diagnostics and No Secrets

Email info@vpnsoeasy.com with the device type, the server location you tried, and what VPNClient displayed, and VPNSoEasy support answers 24/7. Never send a VPN password or private key in that message; support can resolve connection issues with the device and server details alone.

Restore the Handshake Before Changing Traffic Settings

Fix the wireguard handshake first, and only then look at AllowedIPs, forwarding, or DNS. A handshake that never completes and a handshake that completes but passes no traffic are different failures with different fixes, and treating them as one problem wastes time on the wrong layer. Confirm wg show reports a recent handshake timestamp before touching routing, firewall, or NAT settings meant for the next layer of the problem.

Frequently Asked Questions

Can I increase WireGuard’s five-second handshake timeout?

No, the five-second retry interval is a fixed part of the WireGuard protocol and isn’t a configurable setting. WireGuard keeps retrying automatically for about 90 seconds before giving up, so the fix is removing whatever blocks the response, not lengthening the wait.

Why does WireGuard connect on a mobile hotspot but not on Wi-Fi?

This almost always means the Wi-Fi network blocks outbound UDP or the specific WireGuard port, which is common on hotel, campus, and corporate networks. If the same configuration works over cellular data, the network is the obstacle, not your WireGuard setup.

How do I troubleshoot a missing WireGuard handshake on Windows 11 or macOS?

Check that the WireGuard or VPNClient app is allowed through Windows Defender Firewall or macOS’s network permissions, and confirm no other VPN client is competing for the same routes. Restarting the app often resolves a session that shows connected but isn’t exchanging handshake packets.

What should I check on a UniFi or pfSense WireGuard server?

Confirm the firewall rule on the WAN interface allows inbound UDP on the configured port from the client’s public IP, and that the WireGuard interface is administratively up. On these platforms, a rule written on the wrong interface is a frequent cause of a handshake that never completes despite looking correctly configured.

Does PersistentKeepalive fix every missing handshake?

No, persistentkeepalive = 25 only helps when a NAT mapping or firewall state table is closing from inactivity after a handshake has already succeeded once. It does nothing for a handshake that has never completed, which usually points to a blocked UDP port, a key mismatch, or a wrong endpoint instead.