WireGuard «Handshake did not complete after 5 seconds»: 8 causas

Escreves wg show, vês o teu peer, e logo abaixo está a linha que te estraga a noite: latest handshake está vazia, ou o wg-quick avisa handshake did not complete. O teu túnel está de pé no papel mas não passa tráfego. A boa notícia: o WireGuard falha por uma lista curta e finita de razões, e elas surgem numa ordem previsível. Este guia percorre essa ordem do mais comum ao mais raro, para deixares de adivinhar e corrigires em minutos.

O WireGuard é silencioso por design - não envia nada enquanto não houver dados para transportar, e nunca regista um simpático «connection refused». Esse silêncio torna um handshake falhado misterioso. Quase sempre é um problema de alcançabilidade de rede (firewall, porta, NAT, encaminhamento), não de criptografia. Percorre a lista de cima para baixo e vais apanhá-lo.

Pouco tempo? Duas causas explicam a maioria dos handshakes falhados: uma porta UDP que nunca chega ao servidor (firewall fechado, redirecionamento ausente ou CGNAT na sua ligação) e depois, com o túnel ativo, um MTU demasiado alto. O verificador de porta WireGuard indica se está atrás de CGNAT e escreve as regras de redirecionamento e de firewall para o seu sistema; a calculadora de MTU dá o valor a definir quando o handshake funcionar.

Não sabe qual dos dois é? O nosso verificador de porta WireGuard gratuito compara o endereço WAN do router com o seu IP público: em menos de um minuto diz se está atrás de CGNAT (nenhum reencaminhamento vai funcionar) ou se bastam um reencaminhamento e uma regra de firewall.

Atrás de CGNAT? Nenhum redirecionamento de porta nem regra de firewall do teu lado consegue abrir um caminho até um servidor em casa. A saída habitual é correr o servidor WireGuard num VPS com o seu próprio IPv4 público, como um VPS Cloud da Contabo (link de afiliado), desde 5,50 € por mês num prazo de 24 meses (preço lido a 17 de outubro de 2026). Se preferir um fornecedor dos EUA com 30 dias de reembolso, o VPS Basic da Ultahost custa 5,52 $ por mês em 24 meses (1 GB de RAM, IPv4 dedicado, lido a 21 de outubro de 2026), suficiente para um servidor WireGuard com poucos dispositivos. Fornecedor ainda por escolher? Comparativos: melhor VPS para uma VPN e Contabo vs Hetzner vs OVH, pelo preço realmente cobrado. Outra opção: HostPapa Unmanaged VPS Lite (link de afiliado) a 2,95 $ por mês num prazo de 3 anos, depois ao preço normal (1 núcleo, 1 GB de RAM, 25 GB NVMe, acesso root por SSH, garantia de reembolso de 30 dias, consultado a 28 de outubro de 2026).

Ainda não escolheu o servidor? A nossa classificação dos VPS mais baratos para WireGuard compara o que cada fornecedor cobra de facto por um servidor utilizável.

A linha de log exata: "Handshake for peer 1 did not complete after 5 seconds"

Se pesquisaste o erro palavra por palavra, é esta a mensagem que tens à frente. O módulo do kernel Linux imprime-a (depois de ativado o registo de debug), e o wireguard-go, a implementação em espaço de utilizador por trás das apps de Windows, macOS e Android, imprime uma versão quase idêntica:

wireguard: wg0: Handshake for peer 1 (203.0.113.10:51820) did not complete after 5 seconds, retrying (try 2)
wireguard: wg0: Handshake for peer 1 (203.0.113.10:51820) did not complete after 20 attempts, giving up

Como a ler:

• "after 5 seconds" não é uma definição que possas ajustar. É o timeout fixo de nova tentativa do WireGuard (REKEY_TIMEOUT, 5 s no código-fonte). O teu peer enviou uma iniciação de handshake e não recebeu nenhuma resposta válida dentro desse intervalo.
• "retrying (try 2)" significa que ainda está a tentar. O WireGuard continua a reenviar durante cerca de 90 segundos no total.
• "did not complete after 20 attempts, giving up" é o fim desse ciclo. O peer fica em silêncio até que novo tráfego tente atravessar o túnel, o que inicia uma nova ronda.
• Failed to send handshake initiation: no known endpoint for peer é um caso diferente: esse lado não tem Endpoint = para o peer, por isso não consegue iniciar de todo e só pode esperar ser contactado. Normal num servidor; um erro de configuração num cliente.

Em Linux, o módulo do kernel não regista nada por omissão. Para veres estas linhas:

echo module wireguard +p | sudo tee /sys/kernel/debug/dynamic_debug/control
sudo dmesg -w | grep wireguard

A mensagem só prova uma coisa: a iniciação saiu e nada de válido voltou. Não diz porquê. As causas abaixo, por ordem, são o porquê.

Primeiro, lê o estado real com wg show

Antes de mudar o que quer que seja, olha para o que o WireGuard já te diz. Em ambas as pontas:

sudo wg show

Estás a ler três coisas:

• latest handshake - vazio ou mais velho que ~2 minutos = túnel em baixo. Saudável = nos últimos 120 segundos.
• transfer - 0 B received significa que os teus pacotes nunca voltaram. Enviado-mas-nada-recebido é a assinatura de uma firewall ou NAT de sentido único.
• endpoint - no servidor, deve mostrar o IP:porta público atual do cliente assim que chega um pacote. Se nunca se preencher, a iniciação do cliente não te alcançou.

Mantém este terminal aberto. Após cada correção abaixo, executa novamente wg show e observa a linha latest handshake. É a tua única fonte de verdade - não o ícone de ligação, não a app.

wg show latest-handshakes - a forma legível por máquina

Um wg show sozinho imprime um latest handshake: 1 minute, 12 seconds ago pensado para o olho humano. Cómodo de ler, inútil num script. O manual wg(8) permite acrescentar um atributo para restringir a saída:

show { <interface> | all | interfaces } [public-key | private-key | listen-port |
      fwmark | peers | preshared-keys | endpoints | allowed-ips |
      latest-handshakes | persistent-keepalive | transfer | dump]

A forma de referência é portanto:

sudo wg show wg0 latest-handshakes

Imprime uma linha por peer: a chave pública em base64 do peer, uma tabulação, e depois o último handshake em segundos desde a época Unix. É literalmente o que a ferramenta faz: em wireguard-tools, src/show.c contém printf("%s\t%llu\n", key(peer->public_key), peer->last_handshake_time.tv_sec);:

xTIBd0Kx3Hs9tPmVvQ4ZlLxYcE8nRr2A6WKsPqUvT1s=	1750684173
9QzrN7bLyF0mXaHcJdSoEuIgYkTvW3pB5nRfZ1AhQ0M=	0

Duas coisas a saber sobre esse número:

• Um 0 significa que esse peer nunca completou um handshake desde que a interface subiu. Não é um carimbo de tempo velho: é um carimbo ausente. É exactamente o estado que estás a depurar nesta página.
• É um tempo de época absoluto, não uma idade. Subtrai-o de date +%s para obter os segundos decorridos desde o último handshake:

now=$(date +%s)
sudo wg show wg0 latest-handshakes | while read -r peer ts; do
  if [ "$ts" -eq 0 ]; then
    echo "$peer nunca"
  else
    echo "$peer $((now - ts))s atras"
  fi
done

Dois detalhes que mordem quando se escreve o script. wg show all latest-handshakes antepõe o nome da interface como primeira coluna separada por tabulação, por isso o teu read precisa de uma terceira variável. E wg show wg0 dump dá-te o mesmo carimbo de tempo ao lado do endpoint, dos allowed-ips e dos contadores de transferência, numa linha por peer separada por tabulações: é a forma a analisar se estás a construir um monitor a sério e não uma one-liner.

Acima de ~180 segundos num peer que devia estar activo, o túnel está em baixo. É o limiar em que se deve alertar, e o resto desta página é a lista ordenada das razões.

Causa 1 - A porta UDP está bloqueada (o culpado n.º 1)

O WireGuard fala UDP numa única porta - 51820 por omissão. Se essa porta estiver filtrada algalgures no caminho, o pacote de iniciação morre e obténs exatamente o teu sintoma. Para perceberes este valor por omissão, como alterá-lo e abri-lo corretamente, vê que porta o WireGuard usa e como abri-la. Normalmente há duas firewalls a verificar, e esquece-se a primeira:

Firewall do fornecedor cloud (a mais esquecida). Contabo, Hetzner, OVH, AWS - todos têm uma firewall de rede ou grupo de segurança à frente do teu VPS. Uma regra que permita UDP 51820 de qualquer lugar tem de existir aí, separada da firewall do sistema. Na maioria das imagens de VPS da Contabo não há firewall do fornecedor por omissão (bom), mas se ativaste uma, adiciona a regra UDP.

Firewall do sistema no servidor. Verifica e permite:

# ufw (Debian/Ubuntu)
sudo ufw allow 51820/udp
sudo ufw reload

# firewalld (Rocky/Alma/Fedora)
sudo firewall-cmd --add-port=51820/udp --permanent
sudo firewall-cmd --reload

Prova rápida de que a porta é alcançável de fora - a partir da tua máquina cliente:

# envia uma sonda UDP; "open|filtered" sem resposta não é conclusivo,
# mas "open" ou um pacote devolvido confirma a alcançabilidade
nc -u -z -v IP_DO_TEU_SERVIDOR 51820

Teste mais limpo: executa sudo tcpdump -n -i eth0 udp port 51820 no servidor, depois liga a partir do cliente. Se vires pacotes de entrada, a porta está aberta e passas à causa seguinte. Se não vires nada, o pacote é descartado antes de chegar ao WireGuard - fica nesta causa.

Não chega nada e o servidor está em casa? Verifica o CGNAT

Se o «servidor» é um Raspberry Pi, um NAS ou um PC na tua ligação de casa, um tcpdump vazio muitas vezes não tem nada a ver com a firewall. Muitos operadores (quase todos os routers 4G/5G e cada vez mais tarifários de fibra) colocam os clientes atrás de CGNAT: o teu router partilha um único IPv4 público com outros clientes, por isso nenhum reencaminhamento de portas consegue fazer chegar um pacote UDP de entrada à tua máquina. Compara o endereço WAN mostrado pelo router com o que devolve curl -4 ifconfig.me. Se forem diferentes, ou se o router mostrar um endereço em 100.64.0.0/10, estás atrás de CGNAT e o handshake não pode concluir-se com esta configuração.

Tens três saídas: pedir um IPv4 público ao operador (alguns dão-no grátis, outros cobram, muitos recusam), usar IPv6 de ponta a ponta se ambos os lados o tiverem, ou pôr o servidor WireGuard num VPS pequeno com o seu próprio IPv4 público e, se ainda precisares de chegar à máquina de casa, ligá-la ao VPS como cliente. O guia de CGNAT explica o túnel inverso, e o nosso gerador de config WireGuard gratuito escreve os ficheiros de servidor e cliente com chaves que coincidem.

Não sabes se um redirecionamento de porta pode funcionar na tua ligação? O nosso verificador de porta WireGuard gratuito compara o endereço WAN do router com o teu IP público, deteta CGNAT, escreve as regras de redirecionamento e de firewall da tua instalação e dá o teste tcpdump que prova que os pacotes chegam ao servidor.

Funciona em casa mas falha no Wi-Fi de um hotel, escritório ou campus?

Então o servidor está bem e a rede em que se encontra bloqueia o UDP, ou reconhece o WireGuard e corta-o. O teste com tcpdump acima só fica vazio enquanto estiver nessa rede. Se o servidor é seu, mude ListenPort (e o Endpoint do cliente) para UDP 443, a porta que o HTTP/3 já usa, que passa pela maioria dos filtros por porta; o nosso guia da porta do WireGuard explica a alteração. Se só precisa de uma VPN que funcione nessa rede e não gere nenhum servidor, uma aplicação VPN com modo de ofuscação encapsula o túnel por si: o Proton VPN oferece Stealth, em todos os planos, incluindo o gratuito, e o NordVPN oferece NordWhisper, que faz o tráfego VPN parecer tráfego web normal (links de afiliado). Contra a inspeção profunda de pacotes, veja o guia anti-DPI.

Plano pago, Black Friday 2026: a oferta de parceiros da Proton, verificada em 28 de outubro de 2026, é VPN Plus a 2,49 $/mês por 2 anos (59,76 $ nos primeiros 24 meses, depois 83,88 $ por ano), com garantia de reembolso de 30 dias e 10 dispositivos. A página de compra mostra o preço do seu país, e a Proton não divulga data de fim.

Causa 2 - Endpoint errado no cliente

O bloco [Peer] do cliente precisa do IP público real do servidor (ou do nome DNS) e do ListenPort exato:

[Peer]
PublicKey = CHAVE_PUBLICA_SERVIDOR
Endpoint = 203.0.113.10:51820
AllowedIPs = 0.0.0.0/0

Erros comuns que produzem um handshake morto:

• O Endpoint aponta para o IP LAN privado do servidor (10.x / 192.168.x) em vez do público.
• Uma gralha na porta, ou o servidor na verdade escuta noutro ListenPort.
• O IP público do servidor mudou (algumas reinstalações de VPS reatribuem-no). Confirma com curl -4 ifconfig.co no servidor, depois compara com o Endpoint do cliente.

O bloco do peer no servidor não tem linha Endpoint (o servidor aprende-a quando o pacote do cliente chega) - adicionar uma aí é um erro de copiar-colar frequente.

Causa 3 - AllowedIPs errados

AllowedIPs é uma tabela de encaminhamento criptográfica, não uma lista de permissões, e um erro parte em silêncio o tráfego de volta:

• No servidor, o AllowedIPs do peer deve listar apenas o endereço de túnel desse cliente, ex. 10.66.66.2/32. Se dois peers partilharem um intervalo sobreposto, o servidor envia as respostas ao errado e o handshake «completa» e depois morre.
• No cliente, AllowedIPs = 0.0.0.0/0 encaminha tudo pelo túnel (VPN completa). Para split tunneling, lista apenas as sub-redes que realmente encaminhas - vê o nosso guia de encaminhamento em split-tunnel.

Um handshake que tem sucesso brevemente e depois estagna é a assinatura clássica de AllowedIPs sobrepostos no servidor. Torna o intervalo de cada peer único.

Precisas de excluir a tua LAN ou um único endereço de um túnel completo? AllowedIPs não tem sintaxe de "exceto", por isso a nossa calculadora de AllowedIPs gratuita transforma "tudo exceto X" na lista mínima de intervalos IPv4 e IPv6 para colar.

Causa 4 - Timeout NAT (funciona 2 minutos, depois morre)

Se o teu cliente está atrás de NAT (router de casa, 4G/5G, Wi-Fi de hotel) e a ligação fica inativa, o router elimina o mapeamento UDP. O servidor deixa de ter caminho de volta ao cliente e o handshake expira em silêncio. A correção vive no peer que está atrás do NAT:

[Peer]
PublicKey = CHAVE_PUBLICA_SERVIDOR
Endpoint = 203.0.113.10:51820
AllowedIPs = 0.0.0.0/0
PersistentKeepalive = 25

PersistentKeepalive = 25 envia um pacote minúsculo a cada 25 segundos, mantendo o mapeamento NAT aberto. Vinte e cinco segundos ficam abaixo de qualquer timeout NAT comum. Adiciona-o em clientes nómadas e em qualquer peer atrás de um router restritivo. O peer do lado do servidor normalmente não precisa dele.

Causa 5 - O encaminhamento IP está desligado no servidor

Se o handshake completa mas não alcanças a Internet pelo túnel, o servidor não encaminha pacotes entre a interface WireGuard e eth0. Ativa-o:

echo 'net.ipv4.ip_forward=1' | sudo tee /etc/sysctl.d/99-wireguard.conf
sudo sysctl --system

Confirma: sysctl net.ipv4.ip_forward deve devolver 1. Combina-o com a regra de masquerade no teu PostUp (os modelos de configuração prontos a usar incluem estas linhas corretamente):

PostUp = iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
PostDown = iptables -t nat -D POSTROUTING -o eth0 -j MASQUERADE

Causa 6 - Desvio do relógio

O handshake do WireGuard usa marcas temporais para bloquear ataques de repetição. Se o relógio do servidor desviar mais do que alguns minutos - comum em imagens de VPS recentes ou VMs que pausaram - os handshakes são rejeitados como expirados. Corrige o relógio:

sudo timedatectl set-ntp true
timedatectl status   # System clock synchronized: yes

Esta é traiçoeira porque tudo o resto parece perfeito. Se verificaste três vezes porta, chaves e encaminhamento e ainda não obténs nada, verifica o relógio antes de desesperar.

Causa 7 - Chaves não coincidentes (verifica isto por último)

As pessoas vão primeiro às chaves; verifica-as por último, porque um erro de chave é mais raro do que as seis causas acima e produz o mesmo sintoma. A regra é simples:

• A [Peer] PublicKey do servidor = a chave pública derivada da PrivateKey do cliente.
• A [Peer] PublicKey do cliente = a chave pública derivada da PrivateKey do servidor.

Regenera e volta a derivar para teres certeza:

# em cada máquina, deriva a chave pública da sua própria chave privada
echo "CHAVE_PRIVADA_DESTE_HOST" | wg pubkey

Compara essa saída com a PublicKey que o outro lado tem para ti. Uma só chave trocada ou truncada parte o handshake por completo. Já agora, uma PresharedKey (se usada) tem de ser idêntica em ambos os peers - uma diferença aí também mata o handshake. O que a chave pré-compartilhada protege de facto, e como adicioná-la sem derrubar um túnel ativo, está no guia da chave pré-compartilhada do WireGuard.

Para descartar as chaves de uma só vez, o nosso gerador de configuração WireGuard gratuito cria no navegador um novo par de chaves para cada lado e coloca cada chave pública no bloco [Peer] do outro, com uma PresharedKey idêntica nos dois lados.

Causa 8 - O MTU parte o túnel logo após o handshake

A rigor, o MTU raramente bloqueia o handshake (os seus pacotes são pequenos). Mas costuma partir as coisas assim que flui tráfego real: o handshake completa, o ping funciona, depois as páginas web bloqueiam para sempre. Isso é fragmentação. Baixa o MTU do cliente:

[Interface]
MTU = 1380

Encontra o valor certo com um ping «do-not-fragment» para o IP de túnel do servidor, reduzindo até passar:

ping -M do -s 1372 10.66.66.1

1420 serve para a maioria das ligações de fibra; 1380 é um valor por omissão seguro; PPPoE e alguns operadores móveis precisam de 1280. O nosso guia de modelos de configuração explica o ajuste do MTU por tipo de ligação. Se o túnel conecta mas bloqueia em transferências grandes, o guia dedicado corrigir o MTU do WireGuard mostra como medir o valor exato com um ping sem fragmentação e ajustá-lo por tipo de ligação.

Para obter o valor em vez de o adivinhar, a calculadora de MTU WireGuard gratuita parte da maior carga útil que o teu ping sem fragmentação passou (ou só do tipo de ligação) e escreve a linha MTU = da tua configuração.

A ordem de diagnóstico em 60 segundos

Quando um handshake falha, executa esta sequência exata e para na primeira coisa errada:

1. wg show em ambos os lados - há algum latest handshake, algum byte received?
2. tcpdump udp port 51820 no servidor enquanto o cliente liga - chegam pacotes?
3. Se não chega nenhum pacote → firewall / porta / Endpoint (causas 1-2).
4. Se chegam pacotes mas nenhuma resposta volta → AllowedIPs do lado do servidor, NAT, rota de volta (causas 3-4).
5. Se o handshake completa mas não há Internet → ip_forward + masquerade (causa 5).
6. Se tudo parece certo e ainda nada → desvio do relógio, depois chaves, depois MTU (causas 6-8).

Esta ordem segue o percurso do pacote, da acessibilidade ao encaminhamento e depois às causas menos evidentes - percorre-a de cima para baixo e não perderás tempo.

Constrói-o bem desde o início

A maioria dos handshakes falhados vem de uma config cosida à mão a partir de três tutoriais contraditórios. Partir de uma base conhecida e boa num VPS limpo remove a maioria das surpresas. Um Contabo Cloud VPS 4 a 5,50 €/mês dá-te um IPv4 público, root completo, e nenhuma firewall do fornecedor para combater - exatamente as condições em que o WireGuard «simplesmente funciona». Segue a configuração Contabo + WireGuard passo a passo e cola uma config verificada do guia de modelos, e partes de linhas que se sabe funcionarem em conjunto.

Se preferir refazer os dois lados do zero, o nosso gerador de configuração WireGuard gratuito cria as chaves no navegador e escreve configurações de servidor e de cliente coerentes: chaves públicas, AllowedIPs e Endpoint batem certo à primeira.

Para ter o essencial à mão: a WireGuard Cheat Sheet gratuita (PDF de 5 páginas em inglês, download direto, sem registo) 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 correr primeiro quando um túnel não passa tráfego. O WireGuard Self-Hosting Kit pago (9 USD, em inglês) acrescenta uma checklist de diagnóstico com 12 causas e 11 modelos de configuração.

Uma VPN muda o seu IP. Não muda o seu navegador.

Um túnel substitui o endereço que um serviço vê. Não altera nada do que o seu navegador anuncia por conta própria - tipos de letra, ecrã, fuso horário, pilha gráfica - e essa combinação costuma bastar para o reconhecer de uma sessão para a outra.

Meça a sua impressão digital de navegador - medição passiva, sem perguntas, sem conta, sem e-mail.

Para aprofundar

• PersistentKeepalive: o que faz mesmo a definição de 25 segundos
• WireGuard multihop: encadear dois servidores auto-hospedados
• WireGuard atrás de CGNAT: porque o handshake nunca chega
• WireGuard no Windows: configuração passo a passo
• WireGuard no iPhone e iPad: a configuração completa no iOS
• Auto-hospedar VPN na Contabo: guia completo WireGuard 2026
• Modelos de configuração WireGuard prontos a usar 2026
• Fugas de DNS no WireGuard: detetar, diagnosticar, eliminar
• Kill-switch WireGuard no Linux: iptables + systemd
• VPN em split-tunnel com tabelas de encaminhamento
• Glossário de VPN auto-hospedada - AllowedIPs, MTU, NAT explicados
• PiVPN em 2026: a forma mais fácil de auto-hospedar WireGuard ou OpenVPN

Fontes e referências:

• Whitepaper do WireGuard - Jason A. Donenfeld
• Quickstart do WireGuard e docs do wg-quick
• Páginas de manual wg(8) e wg-quick(8)
• Arch Wiki - resolução de problemas do WireGuard

Publicado em 2026-06-23. Comandos escritos para servidores Debian 12 e Ubuntu 24.04 a partir da documentação oficial do WireGuard; não temos um banco de ensaio com vários clientes. As tuas condições de ligação podem variar - confirma sempre com wg show e tcpdump antes de considerar uma correção definitiva.

Lembrete: executar o WireGuard e auto-hospedar uma VPN é legal na UE, EUA, Canadá. A VPNSmith publica este conteúdo para fins educativos.

Também vale a pena auditar onde ficam as chaves: um aviso da CISA de julho de 2026 cobre uma falha do RouterOS que permite ler uma chave privada WireGuard estática a partir do próprio router. Veja porque desativar a API não desfaz isso.