Comment résoudre les échecs de handshake WireGuard (guide de dépannage)

Le handshake de WireGuard est l’échange de clés initial qui doit réussir avant que le moindre trafic puisse passer par le tunnel. Quand il échoue, vous obtenez une connexion qui semble correctement configurée mais qui ne fait jamais réellement passer de données, et les messages d’erreur sont généralement peu utiles, juste un « handshake did not complete » ou rien du tout. Voici comment parcourir les causes réelles dans l’ordre où elles sont le plus susceptibles d’être le problème.

Ce que fait réellement le handshake

WireGuard utilise un cadre cryptographique appelé Noise pour établir une session sécurisée entre votre appareil et le serveur avant que le moindre trafic réel ne circule. Les deux côtés doivent se joindre par UDP, vérifier mutuellement leurs clés publiques, et terminer cet échange en quelques secondes. Si une partie de ce chemin est bloquée, mal configurée, ou incohérente, le handshake échoue silencieusement et retente en boucle plutôt que de renvoyer une erreur claire, ce qui explique pourquoi diagnostiquer la cause demande une vérification méthodique plutôt que la lecture d’un message de log évident.

Étape 1 : confirmer que l’interface est bien active

Lancez sudo wg show sous Linux, ou vérifiez le statut de connexion de votre app sur d’autres plateformes, pour confirmer que l’interface WireGuard est bien active. Si l’interface elle-même n’est pas active, le problème vient de votre fichier de configuration ou de la configuration de l’app, pas du chemin réseau, et le reste de ce dépannage ne s’applique pas encore. Corrigez d’abord les erreurs signalées à ce stade.

Étape 2 : vérifier un port UDP bloqué

WireGuard fonctionne sur UDP, généralement sur le port 51820 par défaut, même si les fournisseurs peuvent utiliser un port différent. Certains réseaux d’hôtel, d’aéroport, d’entreprise et de campus bloquent ou restreignent fortement le trafic UDP sortant en particulier, l’UDP étant moins courant pour la navigation classique et plus associé aux VPN et au jeu vidéo. Essayez de passer temporairement à un partage de connexion mobile pour écarter cette hypothèse : si le handshake se termine instantanément sur un autre réseau, le pare-feu du réseau d’origine est le vrai problème, et aucun ajustement de config de votre côté ne le résoudra. Certains fournisseurs proposent une option d’obfuscation basée sur TCP spécifiquement pour ces réseaux restrictifs, qui vaut le coup si l’UDP est systématiquement bloqué là où vous êtes.

Envie de comparer tous les VPN côte à côte ? Consultez notre tableau comparatif complet avec les scores sur 18 critères.

Étape 3 : revérifier vos clés publique et privée

Une paire de clés incohérente est l’une des causes les plus courantes d’un échec de handshake silencieux, surtout si vous copiez manuellement des clés entre une config client et une config serveur plutôt que d’utiliser l’app d’un fournisseur. Vérifiez que la PrivateKey du client correspond à la clé publique que le serveur a enregistrée pour vous, et que la clé publique du serveur dans votre config client correspond à ce que le serveur présente réellement. Un simple espace en trop, un caractère manquant, ou une clé tronquée par accident lors d’un copier-coller suffit à casser le handshake sans aucun autre symptôme.

Étape 4 : vérifier l’adresse et le port du endpoint

La ligne Endpoint de votre config a besoin de l’adresse IP (ou nom d’hôte) actuelle et correcte du serveur, ainsi que du port. Si un fournisseur a récemment fait tourner ses IP de serveurs, une ancienne config en cache pointant vers une adresse désormais obsolète échouera silencieusement plutôt que de signaler une erreur DNS ou de connexion claire. Retélécharger un fichier de config neuf depuis votre fournisseur, plutôt que de réutiliser un ancien fichier sauvegardé, résout ça dans la plupart des cas.

Étape 5 : ajouter PersistentKeepalive si vous êtes derrière un NAT

Si votre appareil est derrière le NAT d’un routeur domestique, ou pire, le CGNAT d’un opérateur mobile (NAT de niveau opérateur, courant sur les connexions de données mobiles), le serveur peut perdre la capacité de vous recontacter après la tentative de handshake initiale, la correspondance NAT de cette connexion pouvant expirer par inactivité. Ajouter PersistentKeepalive = 25 à la section peer de votre config client indique à WireGuard d’envoyer un petit paquet de maintien toutes les 25 secondes, gardant la correspondance NAT ouverte pour que le serveur puisse toujours vous joindre. Cette seule ligne corrige une grande partie des cas « ça se connecte, puis ça se coupe » et des problèmes de handshake intermittents sur les réseaux mobiles en particulier.

Étape 6 : revoir votre réglage AllowedIPs

Le champ AllowedIPs contrôle quel trafic est routé via le tunnel, et une valeur mal configurée ici peut créer une boucle de routage empêchant les paquets de handshake eux-mêmes d’atteindre la bonne interface. Si vous dépannez plutôt que d’affiner un split tunneling, régler temporairement AllowedIPs = 0.0.0.0/0 (tout le trafic via le tunnel) écarte une mauvaise configuration de routage comme cause, et vous pourrez le resserrer une fois la connexion de base fonctionnelle.

Étape 7 : baisser le MTU si le handshake réussit mais que le trafic ne passe pas

Si wg show rapporte un handshake réussi et récent mais que vous ne pouvez toujours rien charger, un MTU (unité de transmission maximale) trop élevé causant une fragmentation des paquets est un coupable fréquent, en particulier sur les connexions avec une surcharge supplémentaire comme les données mobiles ou certaines configurations de FAI. Essayez de baisser le MTU de votre config à 1280 ou 1380 (contre 1420 par défaut sous WireGuard) et reconnectez-vous. Ce symptôme précis, un handshake réussi sans circulation réelle de données, est l’un des signaux les plus clairs pointant vers le MTU plutôt que vers le processus de handshake lui-même.

Étape 8 : redémarrer proprement plutôt que de se reconnecter sur une session bloquée

Parfois, la solution est vraiment d’éteindre et de rallumer, mais bien le faire compte. Éteignez complètement l’interface (sudo wg-quick down wg0) avant de la relancer, plutôt que d’essayer de vous reconnecter par-dessus une session que WireGuard croit toujours active. Un état d’interface bloqué au niveau du noyau, en particulier après qu’un ordinateur portable sorte de veille, est une cause fréquente et banale qu’un redémarrage propre résout sans avoir besoin d’aucun des dépannages plus poussés ci-dessus.

Quand c’est un problème côté fournisseur, pas le vôtre

Si rien de ce qui précède ne résout le problème, et surtout si la même config fonctionnait bien hier, vérifiez si le serveur spécifique auquel vous vous connectez subit une panne ou une fenêtre de maintenance. Passer à un autre emplacement de serveur via l’app de votre fournisseur est une étape de diagnostic plus rapide que de continuer à dépanner une config peut-être correcte mais pointant vers un serveur simplement hors service. La plupart des grands fournisseurs publient des pages de statut serveur ou des canaux de support où ce type de panne est rapidement reconnu. C’est une vérification de cinq minutes qui évite de perdre beaucoup de temps à douter d’un fichier de config qui n’a en réalité jamais été le problème.

Une checklist rapide pour la prochaine fois

Gardez cet ordre approximatif en tête si ça se reproduit : confirmez que l’interface est active, écartez un port UDP bloqué en testant sur un autre réseau, vérifiez que les clés et l’adresse du endpoint sont à jour, ajoutez PersistentKeepalive si vous êtes sur données mobiles, et vérifiez AllowedIPs et le MTU seulement si les étapes précédentes ne résolvent rien. Parcourir les causes à peu près dans cet ordre, les plus courantes et les plus rapides à vérifier en premier, vous mène à une solution plus vite que de deviner les possibilités les plus obscures avant d’écarter les plus simples.

À lire aussi : WireGuard contre OpenVPN : lequel est le meilleur ? et Comment installer un serveur VPN WireGuard sur Ubuntu Linux.