WireGuard « Required key not available » : les 4 causes

Dans dmesg ou journalctl -k :

wireguard: wg0: Receiving handshake initiation from peer ... (invalid)
wireguard: wg0: Invalid handshake initiation from 203.0.113.7:51820
wireguard: wg0: Packet has unallowed src IP from peer

ou, le plus souvent cité :

Required key not available

Le noyau dit une chose précise : un paquet est arrivé sur une interface WireGuard et aucune clé configurée n'a pu le déchiffrer. Le réseau a fonctionné. La cryptographie, non.

Cette distinction réduit énormément le champ du problème, et c'est pour ça que les réflexes habituels (vérifier le pare-feu ou le port) n'aident presque jamais ici. Si le port était fermé, tu ne verrais rien du tout.

Pourquoi le message ne nomme aucun pair, et ne le fera jamais

Un paquet WireGuard que le noyau ne peut pas déchiffrer est, de son point de vue, impossible à distinguer du bruit. Il n'y a aucun champ expéditeur en clair à lire. Nommer un pair obligerait à deviner, et le protocole est conçu pour ne pas deviner, ce qui rend aussi WireGuard muet face aux scanners de ports.

Le message est donc honnête, et inutile à lui seul. L'information se trouve ailleurs.

Les trois commandes qui la localisent

wg show

Lis la ligne latest handshake de chaque pair. Un pair sans aucun handshake n'en a jamais complété, ce qui oriente vers les clés. Un pair avec un vieux handshake et des compteurs transfer qui montent, c'est un autre problème.

journalctl -k --since "10 minutes ago" | grep -i wireguard

Mets les horodatages en relation avec tes propres tentatives de connexion. Les lignes qui n'apparaissent que quand tu essaies de te connecter sont les tiennes. Celles qui arrivent au compte-gouttes en continu viennent d'Internet, et c'est du bruit.

wg show wg0 public-key

Sur les deux machines. C'est la vérification qui règle la cause la plus fréquente, ci-dessous.

Une rangée de casiers métalliques orange vus de biais, chacun avec une plaque de serrure chromée et une clé restée dedans, une porte entrouverte et une étiquette ronde pendue à sa clé

Cause 1 : une clé publique qui n'est pas celle que tu crois

De loin la plus fréquente. Le serveur détient une clé qui n'est pas celle du client, ou le client détient l'ancienne clé du serveur.

Le piège a une forme bien précise : le PublicKey d'un bloc de pair doit être la clé publique de l'AUTRE machine, jamais la tienne. Copier une config d'un client à l'autre en oubliant de changer cette ligne produit une entrée de pair qui pointe sur elle-même, et chaque paquet échoue.

Vérifie en comparant directement :

wg show wg0 public-key

Lance-la sur le serveur et compare avec le PublicKey du bloc [Peer] du client, caractère par caractère. Puis dans l'autre sens. Deux chaînes Base64 diffèrent d'un seul caractère plus souvent qu'on ne l'imagine, surtout après un copier-coller via une messagerie qui a obligeamment rogné quelque chose.

Cause 2 : une clé pré-partagée d'un seul côté

PresharedKey est mélangée au handshake. Présente d'un côté et absente de l'autre, ou présente des deux côtés avec des valeurs différentes, et les clés dérivées ne correspondent plus.

Le symptôme est identique à celui d'une mauvaise clé publique, c'est pourquoi on passe une heure sur la cause 1 avant de trouver celle-ci. Si tu as ajouté une clé pré-partagée récemment, vérifie les deux extrémités avant toute autre chose. Le mécanisme, et la façon d'en ajouter une sans te bloquer l'accès, sont dans le guide de la clé pré-partagée WireGuard.

Cause 3 : la clé privée a été régénérée

Tout ce qui recrée la paire de clés invalide chaque entrée de pair qui référençait l'ancienne clé publique : réinstaller le client, restaurer un conteneur depuis une image, lancer wg genkey dans un script qui a déjà tourné une fois.

L'indice : ça marchait hier et rien n'a changé dans la config. Rien n'a changé dans le fichier, mais la clé derrière, si. Un serveur qu'on reconstruit sans arrêt (une machine à la maison réinstallée après une panne de disque, un conteneur recréé depuis une image) en est la source habituelle ; un petit VPS avec une IPv4 publique fixe et des snapshots garde la même clé sur le même hôte. Un Contabo Cloud VPS (lien affilié) coûte 5,50 € par mois sur un engagement de 24 mois avec un snapshot inclus (relevé le 17 octobre 2026), et Ultahost VPS Basic (lien affilié) coûte 5,52 $ par mois sur un engagement de 24 mois avec une IPv4 dédiée et une garantie satisfait ou remboursé de 30 jours (relevé le 21 octobre 2026).

Si tu reconstruis la paire de toute façon, génère les deux côtés à partir de la même source. Notre générateur de config WireGuard gratuit crée chaque paire de clés dans ton navigateur et écrit les blocs [Peer] du serveur et chaque fichier client à partir du même matériel, si bien que la clé publique que le serveur détient pour un client est, par construction, celle qui dérive de la clé privée de ce client. Ajoute le nouveau bloc [Peer] au serveur en marche avec wg set ou wg syncconf, comme expliqué dans ajouter un pair WireGuard, et le silence de l'ancienne entrée cesse. Le générateur est gratuit jusqu'à 10 appareils ; au-delà, WireGuard Pro (notre propre produit, 9 EUR une fois, sans abonnement) relève la limite à 250 et ajoute un ZIP avec chaque .conf client et son QR code en PNG, pratique pour équiper tout un bureau ou toute une famille d'un coup.

Cause 4 : ce n'est pas du tout ton trafic

Un serveur qui écoute sur un port UDP public reçoit des paquets non sollicités. Les scanners en envoient en permanence, et chacun produit une ligne.

C'est normal et ça ne demande aucune action. C'est du bruit de fond, qui ne devient un signal que lorsqu'il coïncide avec tes propres tentatives. Si le volume te gêne, changer le port d'écoute le réduit, mais faire taire cette catégorie de logs supprimerait le seul diagnostic dont tu disposes quand un vrai pair échoue.

L'ordre qui la trouve le plus vite

wg show des deux côtés. L'absence totale de handshake confirme un problème de clé plutôt que de routage.
Compare les clés publiques directement avec wg show wg0 public-key, dans les deux sens.
Vérifie si PresharedKey existe d'un côté et pas de l'autre.
Regarde les horodatages. Si les lignes apparaissent sans que tu fasses quoi que ce soit, ce sont des scanners.

Si l'interface n'est jamais montée et que la clé a été rejetée avant toute tentative de handshake, le problème tient à la forme de la clé plutôt qu'à sa valeur : c'est key is not the correct length or format, une erreur d'analyse aux causes complètement différentes.

Si le handshake se complète et que le trafic échoue quand même, tu n'es pas sur le bon article : c'est soit le MTU quand les pages restent bloquées, soit AllowedIPs quand le routage est faux. La checklist plus large se trouve dans le dépannage du handshake.

Garde l'essentiel sous la main : la WireGuard Cheat Sheet gratuite (PDF de 4 pages, prix libre, 0 USD accepté) rassemble les tableaux keepalive et MTU, les commandes wg genkey/wg pubkey/wg genpsk et les quatre vérifications serveur en une ligne à lancer en premier quand un tunnel ne fait passer aucun trafic. Le WireGuard Self-Hosting Kit payant (9 USD) ajoute une checklist de dépannage en 12 causes et 11 modèles de config.

★ Datacenter Nuremberg GDPR · ✓ IPv4 dédiée incluse · port 200 Mbit/s

Héberge ton VPN sur ton propre VPS → ContaboAccès root complet · IPv4 publique · choisis ta région→

Questions fréquentes

Que signifie Required key not available dans WireGuard ?

Le noyau a reçu un paquet chiffré sur une interface WireGuard et n'a trouvé aucun pair dont la clé permette de le déchiffrer. C'est un échec de déchiffrement, pas une panne réseau : le paquet est bien arrivé. Quelque chose dans le matériel cryptographique d'un côté ne correspond pas à l'autre.

Pourquoi l'erreur ne dit-elle pas quel pair a échoué ?

Parce que le noyau ne peut pas le savoir. Un paquet qu'il ne peut pas déchiffrer ne porte aucune identité lisible, donc nommer un pair reviendrait à deviner. Ce silence est une propriété du protocole, pas une lacune du message d'erreur.

Une mauvaise clé pré-partagée peut-elle provoquer cette erreur ?

Oui, et c'est la cause qu'on trouve en dernier. Une clé pré-partagée définie d'un côté et absente ou différente de l'autre produit exactement cette erreur, car elle est mélangée au handshake et le résultat ne correspond plus.

Est-ce que ça veut dire que quelqu'un attaque mon serveur ?

En général, non. Sur un port public, le trafic non sollicité des scanners produit ces lignes à un rythme faible et régulier : c'est du bruit de fond normal. Ça compte seulement quand ça coïncide avec tes propres tentatives de connexion, et c'est à ça que servent les horodatages.

Comment empêcher ces messages de remplir mon journal ?

Corrige l'incohérence plutôt que de faire taire le message. Si les lignes restantes viennent de scanners d'Internet, changer le port d'écoute réduit le volume sans rien masquer, et c'est la seule mesure qui ne te prive pas d'un vrai signal de diagnostic.