WireGuard «Key is not the correct length or format»: 4 cause

Avvii l'interfaccia e vieni fermato prima che qualsiasi cosa si connetta:

Key is not the correct length or format

La chiave a schermo sembra a posto. Tutta la difficoltà di questo errore sta qui: ciò che è sbagliato è di solito un carattere che non puoi vedere.

Che cos'è esattamente una chiave valida

Una chiave WireGuard è di 32 byte di dati grezzi. Scritti in base64, 32 byte sono esattamente 44 caratteri, e l'ultimo è sempre =, il carattere di riempimento. Questo ti dà un test che puoi applicare in un secondo, a occhio o con un comando:

echo -n "$KEY" | wc -c

44 senza a capo, 45 se l'a capo è ancora attaccato. Qualsiasi altro valore non è una chiave, qualunque aspetto abbia.

Lo stesso vale per chiavi private, chiavi pubbliche e chiavi precondivise, dato che tutte e tre sono di 32 byte. Il che porta dritto alla trappola dell'ultima sezione.

Causa 1: un a capo finale invisibile

È la causa singola più comune, e nasce da un comando che sembra del tutto ragionevole:

PRIVATE_KEY=$(cat privatekey)

cat restituisce il file compreso il suo a capo finale, e qui la sostituzione di comando lo rimuove, ma lo stesso valore scritto in una configurazione con un heredoc o una macro dell'editor spesso lo conserva. Scritto in wg0.conf, ottieni una chiave seguita da un carattere di troppo e un valore di 45 byte dove ne servivano 44.

Rimuovilo in modo esplicito invece di sperare:

tr -d '\n' < privatekey

Causa 2: la chiave spezzata su due righe

Copiare una chiave da una finestra di terminale stretta, da un'email o da un client di chat può inserire un'interruzione di riga nel mezzo. Nel file di configurazione il valore ora finisce dopo una trentina di caratteri, e il resto sta su una riga orfana tutta sua.

Cercala con un controllo di lunghezza riga per riga invece di leggere:

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

Ogni riga di chiave deve stampare 44. Qualsiasi altro valore in quell'elenco è il colpevole, e funziona su una configurazione con una dozzina di peer, dove il controllo a occhio non funziona.

Causa 3: la chiave è arrivata in compagnia

Una chiave generata e mostrata in un solo passaggio può raccogliere ciò che le sta intorno. Due varianti:

• Un prompt della shell o l'eco del comando catturati insieme all'output quando copi dal buffer di scrollback.
• Uno spazio iniziale, che il base64 non tollera e che nessun editor ti mostrerà.

Quando si tratta di una chiave nuova, rigenerarla è più rapido che fare indagini:

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

Reindirizzare in un file invece di leggere dallo schermo elimina l'intera categoria di problemi, e il chmod conta perché una chiave privata leggibile da tutti è un problema a sé.

Se stai ancora scrivendo la configurazione, puoi fare a meno del terminale per le chiavi. Il nostro generatore di configurazioni WireGuard gratuito crea le coppie di chiavi nel tuo browser (Curve25519, nulla viene inviato a un server) e le scrive direttamente nell'[Interface] del server, nei suoi blocchi [Peer] e in un file client per dispositivo. Nessuna chiave passa da appunti, righe di terminale spezzate o prompt della shell lungo il percorso, e ogni chiave che scrive è esattamente di 44 caratteri: il controllo awk qui sopra stampa 44 su ogni riga del suo output. Il generatore è gratuito fino a 10 dispositivi; oltre, WireGuard Pro (il nostro prodotto, 9 EUR una tantum, nessun abbonamento) porta il limite a 250 e aggiunge un unico ZIP con ogni .conf client e il relativo codice QR in PNG, comodo per configurare un intero ufficio o una famiglia in un colpo solo.

Causa 4: il tipo di chiave giusto nel posto sbagliato

Questa non produce l'errore, ed è proprio per questo che merita un posto qui. Anche una chiave pubblica è di 44 caratteri base64, quindi metterne una nel campo PrivateKey viene letto perfettamente e fallisce in silenzio per sempre. Nessun messaggio, nessun rifiuto, solo un handshake che non avviene mai.

Il controllo consiste nel derivare invece di confrontare:

wg pubkey < privatekey

Se l'output è uguale al valore nel tuo campo PrivateKey, ci hai messo una chiave pubblica. Una chiave privata passata a wg pubkey ti dà qualcosa di diverso da sé stessa; una chiave pubblica passata allo stesso comando dà dati senza senso o un errore, mai il valore di partenza.

Un controllo in una riga di tutte le chiavi di una configurazione

Invece di testarle una alla volta:

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

Ogni riga deve iniziare con 44. Un numero diverso da 44 indica una chiave rotta, e l'hai trovata senza leggere un solo carattere di base64.

Per avere i comandi delle chiavi sempre a portata di mano (wg genkey, wg pubkey < private.key per verificare che una chiave privata corrisponda alla pubblica che hai incollato, wg genpsk, wg show wg0 latest-handshakes), il nostro WireGuard Cheat Sheet gratuito li raccoglie in una pagina A4 stampabile, insieme alle direttive di configurazione e alle tabelle di MTU e porte. Paghi quanto vuoi, 0 USD accettato. Scarica il cheat sheet.

Dove si presenta il problema successivo

Sistemare il formato ti fa superare la lettura del file e ti porta alla categoria di problemi successiva, cioè un tunnel che si attiva e non fa nulla. Una chiave ben formata ma diversa da quella che l'altro capo si aspetta produce un guasto completamente diverso, trattato in l'errore required key not available.

Due casi vicini vanno distinti da questo. La chiave precondivisa è una terza chiave con la stessa forma di 44 caratteri ma regole simmetriche, quindi è facile metterla nel posto sbagliato: vedi la guida alla chiave precondivisa. E la stessa chiave installata su due dispositivi viene letta senza problemi e si rompe in un modo che sembra casuale, una storia a parte in due dispositivi, una chiave (in inglese).

Se scrivi configurazioni a mano abbastanza spesso da incappare ripetutamente in questo errore, i modelli di configurazione WireGuard eliminano quasi tutta la trascrizione. Se stai costruendo il server da zero, parti da un VPS KVM con il suo IPv4 pubblico, dove wg-quick gira su un kernel che controlli tu: un Contabo Cloud VPS (link di affiliazione) costa 5.50 € al mese con un impegno di 24 mesi (letto il 17 ottobre 2026), e Ultahost VPS Basic (link di affiliazione) costa 5.52 $ al mese con un impegno di 24 mesi, con 1 GB di RAM e una garanzia di rimborso di 30 giorni (letto il 21 ottobre 2026).