WireGuard «Required key not available»: 4 causas e a solução

No dmesg ou no 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, a mais citada:

Required key not available

O kernel está a dizer uma coisa precisa: chegou um pacote a uma interface WireGuard e nenhuma chave configurada o conseguiu decifrar. A rede funcionou. A criptografia não.

Esta distinção estreita enormemente o problema, e é por isso que os reflexos habituais, verificar a firewall ou a porta, quase nunca ajudam aqui. Se a porta estivesse fechada, não verias absolutamente nada.

Porque é que a mensagem não nomeia nenhum peer, e nunca o fará

Um pacote WireGuard que o kernel não consegue decifrar é, do seu ponto de vista, indistinguível de ruído. Não há nenhum campo de remetente em texto claro para ler. Nomear um peer exigiria adivinhar, e o protocolo foi concebido para não adivinhar, o que também torna o WireGuard silencioso perante os scanners de portas.

Portanto a mensagem é honesta, e inútil por si só. A informação está noutro lado.

Os três comandos que a localizam

wg show

Lê a linha latest handshake de cada peer. Um peer sem handshake nenhum nunca completou um, o que aponta para as chaves. Um peer com um handshake antigo e contadores transfer a subir é outro problema.

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

Cruza os carimbos de tempo com as tuas próprias tentativas de ligação. As linhas que só aparecem quando tentas ligar-te são tuas. As linhas que vão chegando continuamente são a internet, e são ruído.

wg show wg0 public-key

Nas duas máquinas. É esta a verificação que resolve a causa mais comum, mais abaixo.

Uma fila de cacifos de metal laranja vistos de lado, cada um com uma placa de fechadura cromada e uma chave deixada nela, uma porta ligeiramente entreaberta e uma etiqueta redonda pendurada na sua chave

Causa 1: uma chave pública que não é a que julgas

De longe a mais frequente. O servidor tem uma chave que não é a do cliente, ou o cliente tem a antiga chave do servidor.

A armadilha tem uma forma específica: PublicKey num bloco de peer tem de ser a chave pública da OUTRA máquina, nunca a tua. Copiar uma configuração entre dois clientes e esquecer de mudar essa linha produz uma entrada de peer que aponta para si própria, e todos os pacotes falham.

Verifica comparando diretamente:

wg show wg0 public-key

Executa-o no servidor e compara com a PublicKey no bloco [Peer] do cliente, carácter a carácter. Depois faz o inverso. Strings Base64 diferem num só carácter mais vezes do que alguém espera, sobretudo depois de uma cópia através de uma aplicação de chat que, muito prestável, cortou alguma coisa.

Causa 2: uma chave pré-partilhada só de um lado

A PresharedKey é misturada no handshake. Presente de um lado e ausente do outro, ou presente nos dois com valores diferentes, e as chaves derivadas deixam de corresponder.

O sintoma é idêntico ao de uma chave pública errada, e é por isso que as pessoas passam uma hora na causa 1 antes de encontrarem esta. Se adicionaste uma chave pré-partilhada recentemente, verifica as duas pontas antes de verificares qualquer outra coisa. O mecanismo, e como adicionar uma sem ficares trancado fora, está no guia da chave pré-partilhada WireGuard.

Causa 3: a chave privada foi regenerada

Tudo o que recria o par de chaves invalida todas as entradas de peer que referenciavam a antiga chave pública: reinstalar o cliente, restaurar um contentor a partir de uma imagem, executar wg genkey num script que já tinha corrido uma vez.

O indício é que ontem funcionava e nada na configuração mudou. Nada no ficheiro mudou, mas a chave por trás dele, sim. Um servidor que está sempre a ser reconstruído, uma máquina de casa reinstalada depois de uma avaria do disco ou um contentor recriado a partir de uma imagem, é a origem habitual; um pequeno VPS com um IPv4 público fixo e snapshots mantém a mesma chave no mesmo host. Um Contabo Cloud VPS (link de afiliado) custa 5.50 € por mês num prazo de 24 meses com um snapshot incluído (lido a 17 de outubro de 2026), e o Ultahost VPS Basic (link de afiliado) custa 5.52 $ por mês num prazo de 24 meses com um IPv4 dedicado e garantia de reembolso de 30 dias (lido a 21 de outubro de 2026).

Se vais reconstruir o par de qualquer forma, constrói os dois lados a partir da mesma fonte. O nosso gerador de configuração WireGuard gratuito cria todos os pares de chaves no teu navegador e escreve os blocos [Peer] do servidor e cada ficheiro de cliente a partir do mesmo material, por isso a chave pública que o servidor tem para um cliente é, por construção, aquela que deriva da chave privada desse cliente. Coloca o novo bloco [Peer] no servidor em funcionamento com wg set ou wg syncconf, como descrito em adicionar um peer WireGuard, e o silêncio da entrada antiga acaba. O gerador é gratuito até 10 dispositivos; acima disso, o WireGuard Pro (produto nosso, 9 EUR num único pagamento, sem assinatura) sobe o limite para 250 e junta um ZIP com cada .conf de cliente e o seu código QR em PNG, prático para configurar um escritório ou uma família inteira de uma só vez.

Causa 4: não é de todo o teu tráfego

Um servidor que escuta numa porta UDP pública recebe pacotes não solicitados. Os scanners enviam-nos constantemente, e cada um produz uma linha.

Isto é normal e não exige nenhuma ação. É ruído de fundo, e só se torna um sinal quando coincide com as tuas próprias tentativas. Se o volume te incomoda, mudar a porta de escuta reduz-o, mas silenciar a categoria de log eliminaria o único diagnóstico que tens quando um peer real falha.

A ordem que o encontra mais depressa

wg show nas duas pontas. Nenhum handshake confirma um problema de chaves e não de encaminhamento.
Compara as chaves públicas diretamente com wg show wg0 public-key, nos dois sentidos.
Verifica se a PresharedKey existe num lado e não no outro.
Olha para os carimbos de tempo. Se as linhas aparecem sem fazeres nada, são scanners.

Se a interface nem sequer chegou a subir e a chave foi rejeitada antes de qualquer tentativa de handshake, o problema é a forma da chave e não o seu valor: trata-se de key is not the correct length or format, uma falha de análise com causas totalmente diferentes.

Se o handshake completa e o tráfego continua a falhar, este não é o artigo certo: trata-se do MTU quando as páginas bloqueiam, ou dos AllowedIPs quando o encaminhamento está errado. A lista de verificação mais ampla está em resolução de problemas de handshake.

Mantém o essencial à mão: a WireGuard Cheat Sheet gratuita (PDF de 4 páginas, pagas o que quiseres, 0 USD aceite) reúne as tabelas de keepalive e MTU, os comandos wg genkey/wg pubkey/wg genpsk e as quatro verificações de servidor numa linha a executar primeiro quando um túnel não passa tráfego. O WireGuard Self-Hosting Kit pago (9 USD) acrescenta uma lista de verificação de 12 causas e 11 modelos de configuração.

★ Datacenter GDPR em Nuremberg · ✓ IPv4 dedicado incluído · porta de 200 Mbit/s

Aloje a sua VPN no seu próprio VPS → ContaboAcesso root completo · IPv4 público · escolha a sua região→

Perguntas frequentes

O que significa Required key not available no WireGuard?

O kernel recebeu um pacote cifrado numa interface WireGuard e não encontrou nenhum peer cuja chave o decifre. É uma falha de decifragem, não uma falha de rede: o pacote chegou. Algo no material de chaves de um lado não corresponde ao do outro.

Porque é que o erro não diz qual peer falhou?

Porque o kernel não tem como saber. Um pacote que não consegue decifrar não transporta nenhuma identidade legível, por isso nomear um peer seria adivinhar. O silêncio é uma propriedade do protocolo e não uma lacuna da mensagem de erro.

Uma chave pré-partilhada errada pode causar isto?

Sim, e é a causa que as pessoas encontram em último lugar. Uma chave pré-partilhada definida num lado e ausente ou diferente no outro produz exatamente este erro, porque é misturada no handshake e o resultado deixa de corresponder.

Isto significa que alguém está a atacar o meu servidor?

Normalmente não. Numa porta pública, o tráfego não solicitado de scanners produz estas linhas a um ritmo baixo e constante, e é ruído de fundo normal. Só importa quando coincide com as tuas próprias tentativas de ligação, e é para isso que servem os carimbos de tempo.

Como impeço que as mensagens encham o meu log?

Corrige a discrepância em vez de silenciar a mensagem. Se as linhas restantes vierem de scanners da internet, mudar a porta de escuta reduz o volume sem esconder nada, e é a única mitigação que não te custa um verdadeiro sinal de diagnóstico.