WireGuard « handshake did not complete » : la liste de fixes complète (2026)

Transparence affiliation — Cet article contient des liens affiliés Contabo. Si tu prends un VPS via eux, nous touchons une commission sans surcoût pour toi. Chaque commande et config ci-dessous est documentée depuis les sources officielles WireGuard et écrite pour être reproductible sur ton propre VPS.

Tu tapes wg show, tu vois ton pair, et juste en dessous se trouve la ligne qui gâche ta soirée : latest handshake est vide, ou wg-quick t'avertit handshake did not complete. Ton tunnel est monté sur le papier mais aucun trafic ne passe. La bonne nouvelle : WireGuard échoue pour une liste courte et finie de raisons, et elles arrivent dans un ordre prévisible. Ce guide déroule cet ordre du plus fréquent au plus rare, pour arrêter de deviner et corriger en quelques minutes.

WireGuard est silencieux par conception — il n'envoie rien tant qu'il n'y a pas de données à transporter, et ne logue jamais un gentil « connection refused ». Ce silence rend un handshake raté mystérieux. Presque toujours c'est un problème de joignabilité réseau (pare-feu, port, NAT, routage), pas de cryptographie. Déroule la liste de haut en bas et tu l'attraperas.

D'abord, lis l'état réel avec wg show

Avant de changer quoi que ce soit, regarde ce que WireGuard te dit déjà. Des deux côtés :

sudo wg show

Tu lis trois choses :

• latest handshake — vide ou plus vieux que ~2 minutes = tunnel tombé. Sain = dans les 120 dernières secondes.
• transfer — 0 B received veut dire que tes paquets ne sont jamais revenus. Envoyé-mais-rien-reçu est la signature d'un pare-feu ou NAT à sens unique.
• endpoint — côté serveur, il doit montrer l'IP:port publique actuelle du client dès qu'un paquet arrive. S'il ne se remplit jamais, l'initiation du client ne t'a pas atteint.

Garde ce terminal ouvert. Après chaque fix ci-dessous, relance wg show et surveille la ligne latest handshake. C'est ta seule source de vérité — pas l'icône de connexion, pas l'appli.

Cause 1 — Le port UDP est bloqué (le coupable n°1)

WireGuard parle UDP sur un seul port — 51820 par défaut. Si ce port est filtré quelque part sur le chemin, le paquet d'initiation meurt et tu obtiens exactement ton symptôme. Pour comprendre ce défaut, comment le changer et l'ouvrir correctement, vois quel port WireGuard utilise et comment l'ouvrir. Il y a en général deux pare-feu à vérifier, et on oublie souvent le premier :

Pare-feu du fournisseur cloud (le plus souvent oublié). Contabo, Hetzner, OVH, AWS — tous ont un pare-feu réseau ou un groupe de sécurité devant ton VPS. Une règle autorisant UDP 51820 depuis n'importe où doit exister là, séparée du pare-feu système. Sur la plupart des images de VPS Contabo il n'y a pas de pare-feu fournisseur par défaut (tant mieux), mais si tu en as activé un, ajoute la règle UDP.

Pare-feu système sur le serveur. Vérifie et autorise :

# ufw (Debian/Ubuntu)
sudo ufw allow 51820/udp
sudo ufw reload

# firewalld (Rocky/Alma/Fedora)
sudo firewall-cmd --add-port=51820/udp --permanent
sudo firewall-cmd --reload

Preuve rapide que le port est joignable de l'extérieur — depuis ta machine client :

# envoie une sonde UDP ; "open|filtered" sans réponse est non concluant,
# mais "open" ou un paquet renvoyé confirme la joignabilité
nc -u -z -v IP_DE_TON_SERVEUR 51820

Test plus propre : lance sudo tcpdump -n -i eth0 udp port 51820 sur le serveur, puis connecte-toi depuis le client. Si tu vois des paquets entrants, le port est ouvert et tu passes à la cause suivante. Si tu ne vois rien, le paquet est jeté avant d'atteindre WireGuard — reste sur cette cause.

Cause 2 — Mauvais Endpoint côté client

Le bloc [Peer] du client a besoin de la vraie IP publique du serveur (ou son nom DNS) et du ListenPort exact :

[Peer]
PublicKey = CLE_PUBLIQUE_SERVEUR
Endpoint = 203.0.113.10:51820
AllowedIPs = 0.0.0.0/0

Erreurs fréquentes qui produisent un handshake mort :

• L'Endpoint pointe sur l'IP LAN privée du serveur (10.x / 192.168.x) au lieu de la publique.
• Une faute de frappe dans le port, ou le serveur écoute en réalité sur un autre ListenPort.
• L'IP publique du serveur a changé (certaines réinstallations de VPS la réattribuent). Confirme avec curl -4 ifconfig.co sur le serveur, puis compare à l'Endpoint du client.

Le bloc pair côté serveur n'a pas de ligne Endpoint (le serveur l'apprend quand le paquet du client arrive) — en ajouter une là est une erreur de copier-coller fréquente.

Cause 3 — Des AllowedIPs erronés

AllowedIPs est une table de routage cryptographique, pas une liste de permissions, et une erreur casse en silence le trafic retour :

• Côté serveur, le AllowedIPs du pair doit lister uniquement l'adresse tunnel de ce client, ex. 10.66.66.2/32. Si deux pairs partagent une plage qui se chevauche, le serveur envoie les réponses au mauvais et le handshake « se complète » puis meurt.
• Côté client, AllowedIPs = 0.0.0.0/0 route tout dans le tunnel (VPN complet). Pour du split tunneling, liste seulement les sous-réseaux que tu routes vraiment — voir notre guide de routage en split-tunnel.

Un handshake qui réussit brièvement puis cale est la signature classique d'AllowedIPs côté serveur qui se chevauchent. Rends la plage de chaque pair unique.

Cause 4 — Timeout NAT (marche 2 minutes puis meurt)

Si ton client est derrière du NAT (box maison, 4G/5G, Wi-Fi d'hôtel) et que le lien devient inactif, le routeur supprime le mapping UDP. Le serveur n'a plus de chemin de retour vers le client et le handshake expire en silence. Le fix vit sur le pair situé derrière le NAT :

[Peer]
PublicKey = CLE_PUBLIQUE_SERVEUR
Endpoint = 203.0.113.10:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

PersistentKeepalive = 25 envoie un petit paquet toutes les 25 secondes, gardant le mapping NAT ouvert. Vingt-cinq secondes est sous tout timeout NAT courant. Ajoute-le sur les clients nomades et sur tout pair derrière un routeur restrictif. Le pair côté serveur n'en a en général pas besoin.

Cause 5 — Le forwarding IP est coupé sur le serveur

Si le handshake se complète mais que tu n'atteins pas Internet via le tunnel, le serveur ne fait pas suivre les paquets entre l'interface WireGuard et eth0. Active-le :

echo 'net.ipv4.ip_forward=1' | sudo tee /etc/sysctl.d/99-wireguard.conf
sudo sysctl --system

Confirme : sysctl net.ipv4.ip_forward doit renvoyer 1. Associe-le à la règle de masquerade dans ton PostUp (les templates de config prêts à l'emploi embarquent ces lignes correctement) :

PostUp = iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

Cause 6 — Décalage d'horloge

Le handshake de WireGuard utilise des horodatages pour bloquer les attaques par rejeu. Si l'horloge du serveur dévie de plus de quelques minutes — fréquent sur les images de VPS fraîches ou les VM mises en pause — les handshakes sont rejetés comme périmés. Corrige l'horloge :

sudo timedatectl set-ntp true
timedatectl status   # System clock synchronized: yes

Celle-ci est sournoise car tout le reste a l'air parfait. Si tu as triple-vérifié le port, les clés et le routage et que tu n'as toujours rien, vérifie l'horloge avant de désespérer.

Cause 7 — Clés non concordantes (à vérifier en dernier)

On se rue d'abord sur les clés ; vérifie-les en dernier, car une erreur de clé est plus rare que les six causes précédentes et produit le même symptôme. La règle est simple :

• La [Peer] PublicKey du serveur = la clé publique dérivée de la PrivateKey du client.
• La [Peer] PublicKey du client = la clé publique dérivée de la PrivateKey du serveur.

Régénère et re-dérive pour être sûr :

# sur chaque machine, dérive la clé publique de sa propre clé privée
echo "CLE_PRIVEE_DE_CET_HOTE" | wg pubkey

Compare cette sortie à la PublicKey que l'autre côté a pour toi. Une seule clé inversée ou tronquée casse complètement le handshake. Au passage, une PresharedKey (si utilisée) doit être identique sur les deux pairs — une différence là tue aussi le handshake.

Cause 8 — Le MTU casse le tunnel juste après le handshake

À proprement parler, le MTU bloque rarement le handshake (ses paquets sont petits). Mais il casse souvent les choses dès que le vrai trafic passe : le handshake se complète, le ping marche, puis les pages web restent bloquées pour toujours. C'est de la fragmentation. Baisse le MTU client :

[Interface]
MTU = 1380

Trouve la bonne valeur avec un ping « do-not-fragment » vers l'IP tunnel du serveur, en réduisant jusqu'à ce que ça passe :

ping -M do -s 1372 10.66.66.1

1420 convient à la plupart des liens fibre ; 1380 est un défaut sûr ; PPPoE et certains opérateurs mobiles exigent 1280. Notre guide des templates de config explique le réglage du MTU par type de lien.

L'ordre de diagnostic en 60 secondes

Quand un handshake échoue, déroule cette séquence exacte et arrête-toi à la première anomalie :

1. wg show des deux côtés — y a-t-il un latest handshake, des octets received ?
2. tcpdump udp port 51820 sur le serveur pendant que le client se connecte — des paquets arrivent-ils ?
3. Si aucun paquet n'arrive → pare-feu / port / Endpoint (causes 1-2).
4. Si des paquets arrivent mais aucune réponse ne revient → AllowedIPs côté serveur, NAT, route de retour (causes 3-4).
5. Si le handshake se complète mais pas d'Internet → ip_forward + masquerade (cause 5).
6. Si tout a l'air bon et toujours rien → décalage d'horloge, puis clés, puis MTU (causes 6-8).

Cet ordre suit la fréquence réelle de chaque cause sur les vraies installations auto-hébergées — déroule-le de haut en bas et tu ne perdras pas de temps.

Bien le construire dès le départ

La plupart des handshakes ratés viennent d'une config recousue à la main depuis trois tutoriels contradictoires. Partir d'une base saine sur un VPS propre supprime 90 % des surprises. Un VPS Contabo S à 4,99 €/mois te donne une IPv4 publique, du root complet, et aucun pare-feu fournisseur à combattre — exactement les conditions où WireGuard « marche tout seul ». Suis le setup Contabo + WireGuard pas-à-pas et colle une config vérifiée depuis le guide des templates, et le handshake passe du premier coup.

Pour aller plus loin

• Self-host VPN sur Contabo : guide complet WireGuard 2026
• Templates de configuration WireGuard prêts à l'emploi 2026
• Fuites DNS WireGuard : détecter, diagnostiquer, éliminer
• WireGuard kill-switch sous Linux : iptables + systemd
• VPN en split-tunnel avec tables de routage
• Glossaire VPN auto-hébergé — AllowedIPs, MTU, NAT expliqués

Sources et références :

• Whitepaper WireGuard — Jason A. Donenfeld
• Quickstart WireGuard et docs wg-quick
• Pages de manuel wg(8) et wg-quick(8)
• Arch Wiki — dépannage WireGuard

Publié le 2026-06-23. Ordre de diagnostic validé sur serveurs Debian 12 et Ubuntu 24.04 avec un VPS Contabo S, face à des clients WireGuard sous Linux, Windows 11, macOS et Android. Tes conditions de lien peuvent différer — confirme toujours avec wg show et tcpdump avant de considérer un fix comme définitif.

Rappel : faire tourner WireGuard et auto-héberger un VPN est légal dans l'UE, aux États-Unis, au Canada et dans la plupart des pays démocratiques. VPNSmith publie ce contenu à des fins éducatives.