WireGuard handshake did not complete: causes

In the WireGuard protocol, the initiator sends one message and waits for a response; "handshake did not complete" means none arrived. The line never says why. In our lab run the initiator printed it for four different faults, and the log on the other end was the only thing that told them apart.

Below: what each fault looks like on both ends, from one dated run on Linux network namespaces, and a test of the claim that a wrong clock stops the handshake. Self-run WireGuard comes first, then a short section for ForestVPN app users.

How do I tell whether a WireGuard handshake ever happened?

Run wg show latest-handshakes on the peer that starts the connection. The wg(8) manual describes the output as each peer's public key followed by a Unix timestamp, and a peer that has never completed one shows 0.

# two outputs from two cases (baseline, and a wrong key), shown together
$ wg show latest-handshakes
1j1ewIgiceU6utI3BHoNNjVR5TYbbZ+KUUqX+7QkPWc=	1793256522   # completed
zWzbIiyPqFcZmY/h/y3lq1xd+TWc3ecPHKYG1senKHs=	0            # never completed

Plain wg show tells the same story in words. A peer with a handshake shows latest handshake: 13 seconds ago; a peer without one has no such line at all, and its transfer counter shows bytes sent and none received.

Do this first, before you touch a config. If the time is non-zero, the handshake is fine and the fault is elsewhere: AllowedIPs (the list of tunnel addresses a peer may send from and receive), routes or packet size. If it is 0, the rest of this page applies.

What does "did not complete after 5 seconds, retrying" mean?

It is the kernel module's retry message: an initiation went out, nothing valid came back, so another is sent, as the protocol page describes for the Noise_IKpsk2 handshake (named here, not modified), and the 5 seconds is the figure our run's log printed. Each retry bumps a counter, so you see (try 2), (try 3) and so on.

Two practical points. The line is a debug message, so it shows up only when dynamic debug is on for the module (module wireguard +p), and our run used exactly that. And it names the endpoint it is retrying, which is the first thing to read: if the address or port in the line is not what you meant to type, you have found the fault.

Apart from the endpoint, the line matched across the four silent cases in our run. That is the finding of this page.

How did we reproduce each fault?

Each case below was set up one at a time on a fresh pair of peers, with the initiator pinging once to start the handshake and about 16 seconds of observation.

What does each fault look like on both ends?

Wrong key: which end shows which line?

A wrong key shows up as a rejected packet on the responder, and the wording depends on which side holds the wrong value. When the responder had a wrong public key for A, it logged Invalid handshake initiation. When A had a wrong public key for B, the responder logged Invalid MAC of handshake, dropping packet. In both, the capture showed 148-byte initiations and no responses.

The protocol page explains the split: the first message carries a MAC keyed to the responder's public key, so a wrong key for the responder fails that check before anything else.

Wrong port or dropped UDP: what is the difference?

Both leave the responder silent, and a packet capture (tcpdump on the veth) is what separates them. With the wrong port, the host at the other end answered every initiation with an ICMP (control-message protocol) "udp port 51821 unreachable", four in all, and WireGuard ignored them: the retry went on regardless. With an nftables input rule on the responder itself dropping UDP 51820, all four initiations arrived at B's interface and there was no reply of any kind.

So silence plus ICMP means the endpoint address is right and nothing listens on that port. Silence without ICMP means the packets get no answer: a firewall on the responder host, a filter on the way, a NAT (network address translation) device that does not pass them, or a wrong address.

Can AllowedIPs stop traffic when the handshake completed?

AllowedIPs can stop traffic without stopping the handshake. On the responder, a wrong range let the handshake finish and wg show printed a handshake time on both ends, yet every ping failed. Only the debug log said why: Packet has unallowed src IP (10.99.0.1) from peer.

On the initiator, a range that excluded the peer's tunnel address left no route, so the ping failed locally with "Network is unreachable" and no initiation was ever sent. If your retry line never appears, check the routes first.

Does a wrong clock stop the WireGuard handshake?

Not for a clock that is simply wrong. VPNsmith lists clock skew as a cause; we tested it rather than repeating it.

In the third case, B refused A's initiations because they carried an older timestamp than the last one B had accepted from that peer. B then started its own handshake, which its kernel log ties to having stopped hearing back from A, and that one completed. The protocol page describes the timestamp in the first message as replay protection, which fits what we saw, though we did not read kernel source.

Narrow result: one offset (a day), and the backward case only on the initiator. A fresh pair with a clock a day off still connected here. A clock that moved backward on a peer the other side remembers can be.

What should I check first, in order?

1. Run wg show latest-handshakes on the initiator. A non-zero time ends the handshake hunt.
2. Read the endpoint in the retry line. Fix a wrong address or port.
3. Read the responder's log. Invalid MAC points at the initiator's copy of the responder's public key. Invalid handshake initiation points at the responder's copy of the initiator's key.
4. If the responder logs nothing, capture UDP on its interface for the listen port. Packets arriving and no reply points first to the responder's input firewall (a capture on the interface runs before those rules, so it still sees dropped packets), then to the listen port or the interface. No packets arriving means look at the path, including NAT.
5. If the handshake completes and pings fail, read AllowedIPs on both peers and the route on the initiator.

Our run set no PersistentKeepalive and used no wg-quick, so we say nothing about either here. If a NAT with a conntrack entry sits in your path, RFC 4787 is the reference for how it treats UDP.

Compare keys by their public values on each end, never by pasting private keys anywhere.

What does ForestVPN's net.blocked_at_handshake mean?

ForestVPN's apps have the matching verdict, named BlockedAtHandshake, with the code net.blocked_at_handshake. The wording differs by client: the desktop reads "We are sending connection attempts and the server is not answering any of them", and the home-screen card reads "Traffic isn't getting through" with the code under Details. Either way the app keeps sending handshake attempts and nothing comes back. That is the situation of the wrong-port and dropped-UDP rows above, seen from the initiator.

As the help page puts it, turn ForestVPN off and on again. If it keeps happening, try a different network, such as mobile data. There is no config file in the app for you to correct. For the full list of connection messages see VPN not connecting and, when the tunnel is up but pages fail, VPN connected but no internet.