WireGuard „Key is not the correct length or format“: Lösung

Du startest die Schnittstelle und wirst gestoppt, bevor irgendetwas eine Verbindung aufbaut:

Key is not the correct length or format

Der Schlüssel auf dem Bildschirm sieht gut aus. Genau das ist die ganze Schwierigkeit bei diesem Fehler: Was falsch ist, ist meistens ein Zeichen, das du nicht sehen kannst.

Was genau ein gültiger Schlüssel ist

Ein WireGuard-Schlüssel besteht aus 32 Bytes Rohdaten. In Base64 geschrieben sind 32 Bytes genau 44 Zeichen, und das letzte ist immer =, das Padding-Zeichen. Damit hast du einen Test, den du in einer Sekunde anwenden kannst, mit bloßem Auge oder per Befehl:

echo -n "$KEY" | wc -c

44 ohne Zeilenumbruch, 45, wenn der Zeilenumbruch noch dranhängt. Alles andere ist kein Schlüssel, egal wie es aussieht.

Dasselbe gilt für Private Keys, Public Keys und Preshared Keys, denn alle drei sind 32 Bytes lang. Das führt direkt zur Falle im letzten Abschnitt.

Ursache 1: ein unsichtbarer Zeilenumbruch am Ende

Die häufigste Einzelursache, und sie stammt aus einem Befehl, der völlig vernünftig aussieht:

PRIVATE_KEY=$(cat privatekey)

cat gibt die Datei einschließlich ihres abschließenden Zeilenumbruchs zurück. Die Command Substitution entfernt ihn hier zwar, aber derselbe Wert, der per Heredoc oder Editor-Makro in eine Konfiguration geschrieben wird, behält ihn oft. In wg0.conf landet dann ein Schlüssel mit einem überzähligen Zeichen dahinter, also ein 45-Byte-Wert, wo 44 verlangt waren.

Entferne ihn explizit, statt auf Glück zu hoffen:

tr -d '\n' < privatekey

Ursache 2: der Schlüssel über zwei Zeilen umgebrochen

Wenn du einen Schlüssel aus einem schmalen Terminalfenster, einer E-Mail oder einem Chat-Client kopierst, kann mitten darin ein Zeilenumbruch landen. In der Konfigurationsdatei endet der Wert dann nach etwa 30 Zeichen, und der Rest steht verwaist in einer eigenen Zeile.

Such danach mit einer Längenprüfung pro Zeile, statt zu lesen:

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

Jede Schlüsselzeile sollte 44 ausgeben. Alles andere in dieser Liste ist dein Übeltäter, und das funktioniert auch bei einer Konfiguration mit einem Dutzend Peers, wo die Prüfung mit bloßem Auge versagt.

Ursache 3: der Schlüssel kam mit Begleitung

Ein Schlüssel, der in einem Schritt erzeugt und angezeigt wird, kann Dinge aus seiner Umgebung mitnehmen. Zwei Varianten davon:

• Ein Shell-Prompt oder ein Befehlsecho, das beim Kopieren aus dem Scrollback-Puffer mit der Ausgabe erfasst wurde.
• Ein führendes Leerzeichen, das Base64 nicht toleriert und das dir kein Editor anzeigt.

Bei einem frischen Schlüssel ist Neuerzeugen schneller als Spurensuche:

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

Die Umleitung in eine Datei, statt den Schlüssel vom Bildschirm abzulesen, beseitigt diese ganze Problemkategorie. Das chmod ist wichtig, weil ein für alle lesbarer Private Key ein eigenes Problem ist.

Wenn die Konfiguration selbst noch geschrieben wird, kannst du das Terminal für die Schlüssel ganz überspringen. Unser kostenloser WireGuard-Konfigurationsgenerator erzeugt die Schlüsselpaare in deinem Browser (Curve25519, nichts wird an einen Server gesendet) und schreibt sie direkt in das [Interface] des Servers, seine [Peer]-Blöcke und eine Client-Datei pro Gerät. Kein Schlüssel wandert dabei durch eine Zwischenablage, eine umgebrochene Terminalzeile oder einen Shell-Prompt, und jeder Schlüssel, den er schreibt, hat genau 44 Zeichen: Die awk-Prüfung oben gibt in jeder Zeile seiner Ausgabe 44 aus. Der Generator ist bis 10 Geräte kostenlos; darüber hinaus hebt WireGuard Pro (unser eigenes Produkt, einmalig 9 EUR, kein Abo) das Limit auf 250 an und liefert ein ZIP mit jeder Client-.conf und ihrem QR-Code als PNG, praktisch, um ein ganzes Büro oder eine ganze Familie in einem Rutsch einzurichten.

Ursache 4: die richtige Art Schlüssel im falschen Feld

Diese Ursache erzeugt den Fehler nicht, und genau deshalb gehört sie hierher. Auch ein Public Key besteht aus 44 Base64-Zeichen, sodass einer im Feld PrivateKey problemlos geparst wird und für immer still scheitert. Keine Meldung, keine Ablehnung, nur ein Handshake, der nie stattfindet.

Die Prüfung besteht darin, abzuleiten statt zu vergleichen:

wg pubkey < privatekey

Wenn die Ausgabe dem Wert in deinem Feld PrivateKey entspricht, hast du dort einen Public Key eingetragen. Ein Private Key, der durch wg pubkey läuft, ergibt etwas anderes als sich selbst; ein Public Key, der durch den Befehl läuft, ergibt Datenmüll oder einen Fehler, niemals den Ausgangswert.

Ein einzeiliger Check aller Schlüssel einer Konfiguration

Statt sie einzeln zu testen:

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

Jede Zeile sollte mit 44 beginnen. Eine Zahl, die nicht 44 ist, steht für einen kaputten Schlüssel, und du hast ihn gefunden, ohne ein einziges Base64-Zeichen zu lesen.

Damit du die Schlüsselbefehle griffbereit hast (wg genkey, wg pubkey < private.key, um zu prüfen, ob ein Private Key zum eingefügten Public Key passt, wg genpsk, wg show wg0 latest-handshakes), bringt unser kostenloses WireGuard Cheat Sheet sie auf eine druckbare A4-Seite, zusammen mit den Konfigurationsdirektiven und den Tabellen zu MTU und Ports. Zahl, was du willst, 0 USD akzeptiert. Cheat Sheet herunterladen.

Wo es als Nächstes hakt

Mit korrektem Format kommst du am Parser vorbei und landest bei der nächsten Problemklasse: einem Tunnel, der hochfährt und nichts tut. Ein Schlüssel, der zwar wohlgeformt, aber nicht der Schlüssel ist, den die Gegenseite erwartet, erzeugt einen ganz anderen Fehler, beschrieben unter dem Fehler „Required key not available“.

Zwei benachbarte Fälle solltest du von diesem trennen. Der Preshared Key ist ein dritter Schlüssel mit derselben 44-Zeichen-Form, aber symmetrischen Regeln, und landet deshalb leicht an der falschen Stelle: siehe den Leitfaden zum Preshared Key. Und derselbe Schlüssel auf zwei Geräten wird problemlos geparst und bricht auf scheinbar zufällige Weise, was eine eigene Geschichte ist, nachzulesen in zwei Geräte, ein Schlüssel (auf Englisch).

Wenn du Konfigurationen oft genug von Hand schreibst, um immer wieder hierauf zu stoßen, nehmen dir die Vorlagen in WireGuard-Konfigurationsvorlagen den Großteil des Abtippens ab. Wenn du den Server selbst von Grund auf aufbaust, starte auf einem KVM-VPS mit eigener öffentlicher IPv4, auf dem wg-quick auf einem Kernel läuft, den du kontrollierst: Ein Contabo Cloud VPS (Affiliate-Link) kostet 5.50 € im Monat bei 24 Monaten Laufzeit (abgelesen am 17. Oktober 2026), und Ultahost VPS Basic (Affiliate-Link) kostet 5.52 $ im Monat bei 24 Monaten Laufzeit, mit 1 GB RAM und 30 Tagen Geld-zurück-Garantie (abgelesen am 21. Oktober 2026).