Erreur WireGuard « Key is not the correct length or format »

Tu démarres l'interface et tout s'arrête avant la moindre connexion :

Key is not the correct length or format

À l'écran, la clé a l'air parfaite. C'est toute la difficulté de cette erreur : ce qui cloche est en général un caractère que tu ne vois pas.

Ce qu'est exactement une clé valide

Une clé WireGuard fait 32 octets de données brutes. En base64, 32 octets donnent exactement 44 caractères, et le dernier est toujours =, le caractère de remplissage. Tu as donc un test applicable en une seconde, à l'œil ou en ligne de commande :

echo -n "$KEY" | wc -c

44 sans saut de ligne, 45 si le saut de ligne est encore attaché. Tout autre résultat n'est pas une clé, quelle que soit son apparence.

C'est vrai pour les clés privées, les clés publiques et les clés pré-partagées, puisque les trois font 32 octets. Ce qui mène directement au piège de la dernière section.

Cause 1 : un saut de ligne final invisible

C'est la cause la plus fréquente, et elle vient d'une commande qui semble tout à fait raisonnable :

PRIVATE_KEY=$(cat privatekey)

cat renvoie le fichier avec son saut de ligne final. Ici, la substitution de commande le supprime bien, mais la même valeur écrite dans une config via un heredoc ou une macro d'éditeur le garde souvent. Une fois dans wg0.conf, tu obtiens une clé suivie d'un caractère parasite, soit une valeur de 45 octets là où il en fallait 44.

Supprime-le explicitement plutôt que d'espérer :

tr -d '\n' < privatekey

Cause 2 : la clé coupée sur deux lignes

Copier une clé depuis une fenêtre de terminal étroite, un e-mail ou une messagerie peut insérer un retour à la ligne en plein milieu. Dans le fichier de config, la valeur s'arrête alors après une trentaine de caractères, et le reste se retrouve seul sur une ligne orpheline.

Cherche-la avec un contrôle de longueur ligne par ligne plutôt qu'en lisant :

awk -F' = ' '/Key/ {print $1, length($2)}' /etc/wireguard/wg0.conf

Chaque ligne de clé doit afficher 44. Toute autre valeur dans cette liste désigne le coupable, et la méthode fonctionne sur une config d'une douzaine de pairs, là où l'inspection à l'œil échoue.

Cause 3 : la clé est arrivée accompagnée

Une clé générée et affichée en une seule étape peut embarquer ce qui l'entoure. Deux variantes :

• Une invite du shell ou l'écho de la commande, capturés avec la sortie lors d'une copie depuis l'historique du terminal.
• Un espace en début de valeur, que le base64 ne tolère pas et qu'aucun éditeur ne te montrera.

Quand il s'agit d'une clé toute neuve, la régénérer va plus vite que l'enquête :

wg genkey > privatekey
chmod 600 privatekey
wg pubkey < privatekey > publickey

Rediriger vers un fichier plutôt que lire la clé à l'écran élimine toute cette catégorie de problèmes, et le chmod compte, car une clé privée lisible par tout le monde est un problème en soi.

Si la config est encore en cours d'écriture, tu peux carrément te passer du terminal pour les clés. Notre générateur de config WireGuard gratuit crée les paires de clés dans ton navigateur (Curve25519, rien n'est envoyé à un serveur) et les écrit directement dans l'[Interface] du serveur, ses blocs [Peer] et un fichier client par appareil. Aucune clé ne passe par un presse-papiers, une ligne de terminal coupée ou une invite du shell en chemin, et chaque clé écrite fait exactement 44 caractères : le contrôle awk ci-dessus affiche 44 sur chaque ligne de sa sortie. Le générateur est gratuit jusqu'à 10 appareils ; au-delà, WireGuard Pro (notre propre produit, 9 EUR une seule fois, sans abonnement) relève la limite à 250 et ajoute un ZIP contenant chaque .conf client et son QR code en PNG, pratique pour équiper tout un bureau ou toute une famille d'un coup.

Cause 4 : le bon type de clé au mauvais endroit

Celle-ci ne produit pas l'erreur, et c'est justement pour ça qu'elle a sa place ici. Une clé publique fait elle aussi 44 caractères base64 : en mettre une dans le champ PrivateKey passe parfaitement la lecture et échoue en silence pour toujours. Aucun message, aucun rejet, juste un handshake qui n'arrive jamais.

La vérification consiste à dériver plutôt qu'à comparer :

wg pubkey < privatekey

Si la sortie est identique à la valeur de ton champ PrivateKey, tu y as mis une clé publique. Une clé privée passée dans wg pubkey donne autre chose qu'elle-même ; une clé publique passée dedans donne n'importe quoi ou une erreur, jamais la valeur de départ.

Un audit en une ligne de toutes les clés d'une config

Au lieu de les tester une par une :

grep -oP '(?<= = )[A-Za-z0-9+/]{40,50}=' /etc/wireguard/wg0.conf | while read k; do
  printf '%s %s\n' "$(printf %s "$k" | wc -c)" "$k"
done

Chaque ligne doit commencer par 44. Un nombre différent de 44 signale une clé cassée, et tu l'as trouvée sans lire un seul caractère de base64.

Pour garder les commandes de clés sous la main (wg genkey, wg pubkey < private.key pour vérifier qu'une clé privée correspond à la clé publique que tu as collée, wg genpsk, wg show wg0 latest-handshakes), notre WireGuard Cheat Sheet gratuite les réunit sur une page A4 imprimable, avec les directives de config et les tableaux MTU et ports. Prix libre, 0 USD accepté. Télécharger la cheat sheet.

Ce qui t'attend ensuite

Corriger le format te fait passer l'étape de lecture et t'amène à la catégorie de problèmes suivante : un tunnel qui monte et ne fait rien. Une clé bien formée mais qui n'est pas celle qu'attend l'autre extrémité provoque une panne totalement différente, traitée dans l'erreur Required key not available.

Deux cas voisins méritent d'être distingués de celui-ci. La clé pré-partagée est une troisième clé, de même forme à 44 caractères mais aux règles symétriques, donc facile à mal placer : voir le guide de la clé pré-partagée. Et la même clé installée sur deux appareils se lit sans erreur et casse d'une façon qui semble aléatoire, une autre histoire racontée dans two devices, one key (en anglais).

Si tu écris des configs à la main assez souvent pour tomber régulièrement sur cette erreur, les modèles de templates de configuration WireGuard suppriment l'essentiel de la recopie. Si tu montes le serveur lui-même de zéro, commence sur un VPS KVM avec sa propre IPv4 publique, où wg-quick tourne sur un noyau que tu contrôles : un Contabo Cloud VPS (lien affilié) coûte 5.50 € par mois sur un engagement de 24 mois (relevé le 17 octobre 2026), et Ultahost VPS Basic (lien affilié) coûte 5.52 $ par mois sur un engagement de 24 mois avec 1 Go de RAM et une garantie satisfait ou remboursé de 30 jours (relevé le 21 octobre 2026).