WireGuard «handshake did not complete»: a lista completa de correções (2026)

Divulgação de afiliados — Este artigo contém links de afiliado da Contabo. Se contratares um VPS através deles, ganhamos uma comissão sem custo extra para ti. Cada comando e configuração abaixo está documentado a partir de fontes oficiais do WireGuard e escrito para ser reproduzível no teu próprio VPS.

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.

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.

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.

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.

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.

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.

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 a frequência real de cada causa em instalações self-host reais — 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 90% das surpresas. Um VPS Contabo S a 4,99 €/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 o handshake completa à primeira tentativa.

Para aprofundar

• 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

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. Ordem de diagnóstico validada em servidores Debian 12 e Ubuntu 24.04 com um VPS Contabo S, contra clientes WireGuard em Linux, Windows 11, macOS e Android. 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á e na maioria dos países democráticos. A VPNSmith publica este conteúdo para fins educativos.