Australian cloud for business software — built and run in Sydney since 2002

NetLeverage
NetLeverage

WireGuard "handshake did not complete": find which side is wrong

Technical article
Troubleshooting

About this article: This article is reviewed against the cited sources. This is source research, not lab validation. Check the stated versions and your own requirements before making changes.

When a WireGuard peer sends a handshake initiation and gets no valid reply, the Linux kernel driver logs Handshake for peer ... did not complete after 5 seconds, retrying (try 2) and sends again. The message only appears if debug logging is switched on, because WireGuard is silent by default. The causes are few: the initiation never reaches the other end (wrong endpoint, UDP blocked), it reaches it and is dropped (wrong public key), or the reply cannot get back. Work from wg show on both ends, then a packet capture.

What the error means

WireGuard has no negotiation to read. The Protocol page says it is "connection-less": you bring the device up and "everything else is handled for you automatically." A handshake is a two-message exchange that sets session keys. The Protocol page lists when a peer starts one, for example "If we have sent a packet to a given peer but have not received a packet after from that peer for KEEPALIVE + REKEY_TIMEOUT ms, we initiate a new handshake."

The kernel source gives the exact numbers. REKEY_TIMEOUT is 5 seconds, and MAX_TIMER_HANDSHAKES is 90 divided by 5, which is 18. After each 5 seconds with no reply the driver logs the "retrying" message and sends another initiation. Once the retries pass the limit, the source logs Handshake for peer ... did not complete after 20 attempts, giving up, drops queued packets, and stops trying until a new packet is queued. The Protocol page describes the same behaviour: retries after REKEY_TIMEOUT plus a random 0 to 333 ms, and giving up after REKEY_ATTEMPT_TIME.

These messages are written with the kernel's debug print calls, and each line starts with the interface name, as in wg0: Handshake for peer 1 (203.0.113.5:51820) did not complete after 5 seconds, retrying (try 2); search for the part after the prefix. If neither peer has anything to send, no handshake is attempted and the message cannot appear. The "Behind NAT" fix covers that case.

The WireGuard Quick Start says that on a kernel with dynamic debugging you can get runtime output with modprobe wireguard && echo module wireguard +p > /sys/kernel/debug/dynamic_debug/control. Userspace implementations use the LOG_LEVEL=verbose environment variable.

The responder is quiet on purpose. In the kernel receive code, a handshake packet with an invalid MAC is dropped with the debug message Invalid MAC of handshake, dropping packet from <address>, and one from an unknown peer key with Invalid handshake initiation from <address>. Neither sends a reply, so the initiator only sees silence.

Likely causes

Cause What you see How to confirm
Wrong endpoint address or port on the initiator Initiator's transfer counter shows bytes sent and none received wg show wg0 endpoints; capture on the responder sees nothing
UDP port blocked by a firewall, security group or NAT Capture on the responder sees nothing, or sees requests and no replies leave tcpdump on both ends on the UDP port
Wrong public key for the responder, on the initiator Responder may log Invalid MAC of handshake; the Protocol page's keyed-MAC description fits a wrong responder key, but WireGuard does not document that as an error mapping Compare wg show wg0 public-key on the responder with the peer key configured on the initiator
Initiator's public key not in the responder's peer list Responder logs Invalid handshake initiation Compare the initiator's public-key with the peers on the responder
Reply cannot return (NAT mapping expired, asymmetric path) Capture shows requests arriving and replies leaving, but the initiator receives none Capture on the initiator

Prove the cause before changing anything

On both ends:

wg show wg0
wg show wg0 public-key
wg show wg0 listen-port
wg show wg0 endpoints
wg show wg0 allowed-ips
wg show wg0 latest-handshakes
wg show wg0 transfer

The wg(8) manual lists these show fields. With no field named, wg show prints everything "in a visually pleasing way meant for the terminal". Naming one field prints it for scripts. The manual does not give the exact output for a peer that has never completed a handshake, so read latest-handshakes as: a recent value means a handshake did complete, and a missing or old value means it did not. transfer gives bytes received and sent per peer.

Compare four things:

  1. The peer's public key on each end must equal the other end's own public-key. A single changed character breaks the handshake.
  2. The initiator's endpoint must be the responder's real address and the port from the responder's listen-port.
  3. If the initiator's transfer shows sent bytes growing and received at zero, packets leave and nothing valid returns.
  4. If both ends have the same peer entries and the keys match, the fault is in the network path.

Then capture the UDP port on the responder and the initiator:

tcpdump -n -i eth0 udp port 51820

-n stops name lookups and -i picks the interface; udp port is a pcap-filter expression, documented as matching source or destination port. Use your own interface and port. If the initiator's capture shows packets leaving and the responder's shows none, a firewall or a wrong endpoint is between them. If the responder sees them, the responder is dropping them. If the responder replies and the initiator's capture shows nothing arriving, the return path is the problem.

To see which drop it is, switch on debug logging on the responder, which is kernel-level and noisy:

modprobe wireguard && echo module wireguard +p > /sys/kernel/debug/dynamic_debug/control
dmesg

Risk: this enables debug prints for the whole WireGuard module and can flood the kernel log on a busy gateway. To back out, write the removal form to the same control file that you used to switch it on: echo module wireguard -p > /sys/kernel/debug/dynamic_debug/control. The kernel dynamic-debug documentation describes the -p form for /proc/dynamic_debug/control and notes that the file appears under the debugfs mount as well, so use whichever path exists on your kernel. Apply it as soon as you have the lines you need.

The Protocol page says the first MAC is keyed with a hash of the responder's static public key, so Invalid MAC of handshake can point to a wrong responder public key on the initiator. WireGuard does not document that as an error mapping, so check the keys on both ends.

Example (illustrative): branch01 (public address 198.51.100.10) initiates to gw01 at 203.0.113.5 on port 51820. On branch01, wg show wg0 shows the peer's endpoint as 203.0.113.5:51820, and transfer shows 3 KiB sent and 0 B received. tcpdump -n -i eth0 udp port 51820 on gw01 shows packets arriving from 198.51.100.10, so the network path works. With debug on, dmesg on gw01 prints Invalid handshake initiation from 198.51.100.10:.... The administrator compares keys and finds gw01 lists a branch01 key with one character wrong. Correcting it on gw01 fixes the handshake.

Fix

Wrong key

Set the correct public key for the peer. The manual gives the command form:

wg set wg0 peer <base64-public-key> allowed-ips 10.0.0.2/32 endpoint 198.51.100.10:51820

Risk: wg set changes the live interface at once. A wrong allowed-ips or endpoint on a production gateway drops traffic for that peer, and allowed-ips also decides which source addresses the gateway accepts from it. Before you change anything, record the current values with wg show wg0 allowed-ips and wg show wg0 endpoints. To back out, run wg set again with the recorded values. The manual does not say that wg set writes your configuration file.

Remove the wrong peer entry with wg set wg0 peer <old-key> remove, as the manual describes ("if the remove argument is given for a peer, that peer is removed").

Disruptive step: removing a peer drops its session at once. Record its allowed-ips and endpoint first (wg show wg0 allowed-ips, wg show wg0 endpoints). Back out by adding it again with the same key and the recorded values. Edit your saved configuration file as well: the manual describes wg set as changing the interface's configuration, and does not say it writes your file.

To load a corrected file without disturbing other peers, the manual describes wg syncconf, which "reads back the existing configuration first and only makes changes that are explicitly different" and so avoids "disrupting current peer sessions."

Risk: wg syncconf applies the whole file to the live interface, so a wrong file changes or removes peers. Keep the previous file, and back out by running wg syncconf with it.

Wrong endpoint or blocked port

Correct the endpoint with wg set wg0 peer <key> endpoint <ip>:<port>.

Risk: pointing a peer at a wrong endpoint stops its handshake until you correct it. Back out by setting the endpoint you recorded earlier.

Allow inbound UDP on the responder's listen-port from the initiator's address, in every layer that filters: host firewall, security group, the provider's network ACL and any NAT port forward. See the page titled "Validating firewall changes for hosted application dependencies" for a safe method.

Risk: a firewall, security group or NAT change applies to everything the rule covers, not only WireGuard. A rule that is too wide exposes more than the listen port, and a mistaken change to an existing rule can cut your own access. Open the one UDP port from the initiator's address only, keep a console or an out-of-band route, and back out by removing the rule you added or restoring the earlier rule set.

Behind NAT

If one side sits behind NAT or a stateful firewall and must be reachable even when idle, add a persistent keepalive. The Quick Start says: "A sensible interval that works with a wide variety of firewalls is 25 seconds." The manual's form is:

wg set wg0 peer <key> persistent-keepalive 25

The default is off, and the manual says "most users will not need this."

Risk: a keepalive makes the peer send a packet every 25 seconds even when it is idle, so the link is no longer silent, which the Quick Start says makes WireGuard "slightly more chatty". To back out, set the value back to 0, which the Quick Start says turns the feature off.

Interface not up

The Quick Start's bring-up step is ip link set up dev wg0. Confirm the interface exists and is up before you chase keys.

Risk: bringing the interface up starts it passing traffic for its allowed IPs. To back out, take it down with ip link set down dev wg0; the ip-link manual says up and down change the state of the device to UP or DOWN.

Confirm the fix

  1. wg show wg0 latest-handshakes shows a recent time for the peer on both ends.
  2. wg show wg0 transfer shows bytes both received and sent.
  3. Real traffic passes. A handshake only proves the keys and path. If it completes but data does not flow, check allowed-ips: the kernel source logs Packet has unallowed src IP for packets whose source address is not in the sending peer's allowed list. A tunnel that comes up and then stalls on large transfers is a separate fault, covered in "Small Requests Work but Large Transfers Hang: Proving a Path MTU Black Hole".
  4. Debug logging is off again.

What to watch afterwards

  • latest-handshakes age on key peers. The Protocol page says "This handshake occurs every few minutes".
  • Peer key changes: a rebuilt server generates new keys, and every peer's configuration must change.
  • Changes to firewalls or NAT in front of the endpoint.

Risks and limits

  • These commands have not been run or lab-tested. They are taken from the WireGuard pages, the wg(8) manual and the kernel source cited in Sources.
  • The log messages quoted are from the Linux kernel driver. Other implementations, such as userspace Go, Windows and BSD ports, use different text.
  • The kernel debug lines depend on dynamic debug being built into your kernel.
  • The wg(8) manual does not show the output of wg show for a peer that has never completed a handshake, so it is described in words here.
  • Keys, endpoint addresses and ports in the example are made up. Never paste private keys into tickets or chat.

Sources

  • WireGuard Quick Start — wireguard.com, copyright 2015-2022 in footer, accessed 18 November 2026
  • WireGuard Protocol & Cryptography — wireguard.com, copyright 2015-2022 in footer, accessed 18 November 2026
  • wg(8) — WireGuard tools via man7.org, page obtained 2026-08-04, accessed 18 November 2026
  • timers.c, WireGuard driver — Linux kernel source, master branch, no date shown, accessed 18 November 2026
  • messages.h, WireGuard driver — Linux kernel source, master branch, no date shown, accessed 18 November 2026
  • receive.c, WireGuard driver — Linux kernel source, master branch, no date shown, accessed 18 November 2026
  • Dynamic debug — The Linux Kernel documentation, no date shown, accessed 18 November 2026
  • ip-link(8) — Linux man-pages project, page obtained 2026-08-04, accessed 18 November 2026
  • tcpdump(1) (page shows "Updated: 10 September 2026") and pcap-filter(7) (page shows "Updated: 16 September 2026") — tcpdump project, accessed 18 November 2026