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

Arrancas la interfaz y te frena antes de que nada se conecte:

Key is not the correct length or format

La clave en pantalla parece correcta. Esa es toda la dificultad de este error: lo que está mal suele ser un carácter que no ves.

Qué es exactamente una clave válida

Una clave WireGuard son 32 bytes de datos en bruto. Escritos en base64, 32 bytes son exactamente 44 caracteres, y el último es siempre =, el carácter de relleno. Eso te da una prueba que puedes aplicar en un segundo, a ojo o con un comando:

echo -n "$KEY" | wc -c

44 sin salto de línea, 45 si el salto de línea sigue pegado. Cualquier otra cosa no es una clave, por mucho que lo parezca.

Lo mismo vale para claves privadas, claves públicas y claves precompartidas, ya que las tres son de 32 bytes. Lo que lleva directamente a la trampa de la última sección.

Causa 1: un salto de línea final invisible

La causa individual más frecuente, y viene de un comando que parece del todo razonable:

PRIVATE_KEY=$(cat privatekey)

cat devuelve el archivo incluido su salto de línea final, y aquí la sustitución de comandos sí lo elimina, pero el mismo valor escrito en una configuración con un heredoc o una macro del editor a menudo lo conserva. Escrito en wg0.conf, obtienes una clave seguida de un carácter sobrante y un valor de 45 bytes donde se exigían 44.

Elimínalo de forma explícita en lugar de confiar en la suerte:

tr -d '\n' < privatekey

Causa 2: la clave partida en dos líneas

Copiar una clave desde una ventana de terminal estrecha, un correo o un cliente de chat puede insertar un salto de línea en medio. En el archivo de configuración el valor termina ahora tras unos 30 y pico caracteres, y el resto queda en su propia línea huérfana.

Búscala con una comprobación de longitud por línea en lugar de leer:

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

Cada línea de clave debe mostrar 44. Cualquier otro valor de esa lista es el culpable, y esto funciona en una configuración con una docena de peers, donde revisar a ojo no funciona.

Causa 3: la clave vino acompañada

Una clave generada y mostrada en un solo paso puede arrastrar cosas a su alrededor. Dos versiones de esto:

• Un prompt de la shell o el eco del comando, capturados junto con la salida al copiar desde el historial de desplazamiento de la terminal.
• Un espacio inicial, que base64 no tolera y que ningún editor te va a mostrar.

Regenerar es más rápido que investigar cuando se trata de una clave nueva:

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

Redirigir a un archivo en lugar de leerla de la pantalla elimina toda esta categoría de problemas, y el chmod importa porque una clave privada legible por todos es un problema en sí misma.

Si todavía estás escribiendo la configuración, puedes prescindir de la terminal para las claves. Nuestro generador de configuración WireGuard gratuito crea los pares de claves en tu navegador (Curve25519, nada se envía a un servidor) y los escribe directamente en el [Interface] del servidor, sus bloques [Peer] y un archivo de cliente por dispositivo. Ninguna clave pasa por un portapapeles, una línea de terminal partida o un prompt de la shell por el camino, y cada clave que escribe tiene exactamente 44 caracteres: la comprobación awk de arriba muestra 44 en cada línea de su salida. El generador es gratuito hasta 10 dispositivos; a partir de ahí, WireGuard Pro (nuestro propio producto, 9 EUR en un único pago, sin suscripción) sube el límite a 250 y añade un ZIP con cada .conf de cliente y su código QR en PNG, práctico para configurar una oficina o una familia entera de una vez.

Causa 4: el tipo de clave correcto en el campo equivocado

Esta no produce el error, y precisamente por eso tiene su sitio aquí. Una clave pública también tiene 44 caracteres base64, así que ponerla en el campo PrivateKey se analiza perfectamente y falla en silencio para siempre. Ningún mensaje, ningún rechazo, solo un handshake que nunca ocurre.

La comprobación consiste en derivar en lugar de comparar:

wg pubkey < privatekey

Si la salida es igual al valor de tu campo PrivateKey, has puesto ahí una clave pública. Una clave privada pasada por wg pubkey te da algo distinto de sí misma; una clave pública pasada por él da basura o un error, nunca el valor del que partiste.

Una auditoría de una línea de todas las claves de una configuración

En lugar de probarlas una por una:

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

Cada línea debe empezar por 44. Un número distinto de 44 es una clave rota, y la has encontrado sin leer un solo carácter de base64.

Para tener a mano los comandos de claves (wg genkey, wg pubkey < private.key para comprobar que una clave privada corresponde a la pública que pegaste, wg genpsk, wg show wg0 latest-handshakes), nuestra WireGuard Cheat Sheet gratuita los reúne en una sola página A4 imprimible con las directivas de configuración y las tablas de MTU y puertos. Paga lo que quieras, se aceptan 0 USD. Descargar la cheat sheet.

Dónde aparece esto después

Corregir el formato te permite superar el análisis y entrar en la siguiente clase de problema: un túnel que se levanta y no hace nada. Una clave bien formada pero que no es la que espera el otro extremo produce un fallo totalmente distinto, tratado en el error required key not available.

Conviene distinguir de este dos casos cercanos. La clave precompartida es una tercera clave con la misma forma de 44 caracteres pero reglas simétricas, así que es fácil colocarla mal: consulta la guía de la clave precompartida. Y la misma clave instalada en dos dispositivos se analiza sin problema y falla de una forma que parece aleatoria, una historia aparte en dos dispositivos, una clave (en inglés).

Si escribes configuraciones a mano con la frecuencia suficiente como para toparte con esto una y otra vez, las plantillas de plantillas de configuración WireGuard eliminan la mayor parte de la transcripción. Si estás montando el propio servidor desde cero, empieza con un VPS KVM con su propia IPv4 pública, donde wg-quick se ejecuta sobre un kernel que controlas: un Contabo Cloud VPS (enlace de afiliado) cuesta 5.50 € al mes con un compromiso de 24 meses (consultado el 17 de octubre de 2026), y Ultahost VPS Basic (enlace de afiliado) cuesta 5.52 $ al mes con un compromiso de 24 meses, con 1 GB de RAM y garantía de devolución de 30 días (consultado el 21 de octubre de 2026).