WireGuard has rapidly become the VPN protocol of choice for its simplicity, security, and performance. However, when connectivity issues occur they can be subtle: a single misconfigured allowed IP, an MTU mismatch, or a firewall rule can break a tunnel. This article provides a practical, technical toolkit to diagnose and fix WireGuard problems quickly — aimed at site operators, dev teams, and network engineers. The guidance below focuses on reproducible checks, relevant commands, and common failure modes so you can restore connectivity with confidence.

Initial verification: Is the interface up?

Start with the basics. Confirm the kernel module and interface are present and active:

  • ip link show — look for the WireGuard interface (commonly wg0, wg1).
  • wg — the WireGuard userspace utility reports peers, public keys, latest handshake, transfer counters, and persistent keepalive.
  • systemctl status wg-quick@wg0 (or your service name) and journalctl -u wg-quick@wg0 -n 200 — check for startup errors and kernel messages.

Example outputs to check:

  • ip link show wg0 should show UP and appropriate MTU.
  • wg show should show peers with non-zero transfer counters and recent “latest handshake” timestamps when active.

Peer handshake and keys

WireGuard requires correct keypairs and a successful handshake. Confirm the following:

  • Public keys in each peer’s configuration must exactly match the counterpart.
  • Keep an eye on “latest handshake” in wg show. If it’s static or shows “never”, the peers have not successfully established a session.
  • Check that the local private key is readable only by the user that runs wg-quick/systemd service (chmod 600 recommended).

If handshakes never occur:

  • Validate that the public endpoint address/port is reachable (see next section).
  • Confirm no NAT is dropping UDP packets — use UDP port forwarding rules if the peer is behind a NAT gateway.

Testing reachability

Use these commands from each peer to ensure UDP connectivity and routing to the endpoint:

  • nc -u -v or nping --udp -p — tests UDP reachability when WireGuard is not interpreting the packets.
  • tcpdump -i eth0 udp port on server — verify that packets arrive at the server’s external interface.

On systems with strict firewalls, ensure the WireGuard port is open for UDP (default 51820) and properly forwarded if behind NAT. For example, on an iptables-based gateway:

  • iptables -t nat -A PREROUTING -p udp --dport 51820 -j DNAT --to-destination 10.0.0.2:51820
  • iptables -A FORWARD -i eth0 -o wg0 -p udp --dport 51820 -m state --state NEW,ESTABLISHED -j ACCEPT

Routing, AllowedIPs and split tunneling

One of the most common misconfigurations is improper AllowedIPs. WireGuard’s AllowedIPs setting functions as policy routing: it determines which IPs are reachable over the tunnel and what traffic will be sent to the peer.

Checklist:

  • Ensure AllowedIPs cover the remote subnets you expect to reach and do not overlap incorrectly with local networks.
  • To push a default route over the tunnel, use 0.0.0.0/0 for IPv4 (and ::/0 for IPv6). If you only want select routes, specify them precisely (e.g., 10.10.0.0/24).
  • On Linux, confirm policy routing rules if you’re using multiple tables (ip rule show and ip route show table ).

Example troubleshooting command to see what route matches an IP:

  • ip route get 8.8.8.8 — will show which interface and gateway would handle the packet.

Firewall, IP forwarding and NAT

Ensure the host is configured to forward packets and that firewall rules do not block traffic:

  • Enable IP forwarding: sysctl net.ipv4.ip_forward=1 (and net.ipv6.conf.all.forwarding=1 for IPv6).
  • Confirm with sysctl net.ipv4.ip_forward or check /proc/sys/net/ipv4/ip_forward.
  • For internet access via the server, add masquerading: iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE (or appropriate nft/mangle rules).

Inspect firewall rules that might silently drop UDP: use iptables -L -n -v and iptables -t nat -L -n -v, or for nftables, nft list ruleset.

MTU, fragmentation and MSS clamping

Performance and connectivity issues frequently stem from an MTU mismatch. WireGuard adds overhead; tunneling packets larger than the path MTU will be dropped if ICMP fragmentation-needed messages do not flow correctly.

Investigation steps:

  • Check the interface MTU: ip link show wg0. Typical default is 1420–1424 for WireGuard (depending on IPv4/IPv6 and additional encapsulation).
  • Test path MTU: ping -M do -s 1350 . Reduce size until it succeeds to find working MTU.
  • Consider enabling MSS clamping on the firewall for TCP flows through the tunnel: iptables -t mangle -A FORWARD -p tcp --tcp-flags SYN,RST SYN -j TCPMSS --clamp-mss-to-pmtu.

When using mobile networks or complex NAT, set a conservative MTU at the WireGuard interface or in the peer config (MTU = 1280 for aggressive compatibility).

DNS issues and split DNS

Often connectivity appears broken because DNS resolution fails rather than the tunnel forwarding traffic. Validate DNS behavior:

  • From inside the tunnel, test name resolution: dig +short @ example.com and ping 1.1.1.1.
  • If DNS queries leak to the local network, configure the client to use a DNS server accessible over the tunnel (e.g., via the interface or a pushed DNS setting in your client configuration).
  • For systemd-resolved, ensure the Link settings are applied: resolvectl status wg0.

Remember that specifying a DNS server in the WireGuard client config (e.g., in wg-quick config) is processed by the client OS tooling, not WireGuard itself.

Performance profiling and throughput bottlenecks

If connections are established but throughput is poor, profile both CPU and network:

  • Measure raw throughput: iperf3 -c over UDP/TCP.
  • Observe CPU usage on both ends. WireGuard uses modern crypto and is fast, but CPU limits, high context switching, or lack of NIC offload can bottleneck performance. Use htop or top.
  • Investigate NIC offloads and ethtool settings: ethtool -k eth0; consider disabling GRO/LRO in virtualization environments that cause issues.
  • Check for packet drops: ip -s link show wg0 and check interface statistics on the physical NICs.

Capturing and interpreting packets

A packet capture can reveal whether UDP wire packets arrive, if they contain WireGuard handshakes, and whether payloads traverse the tunnel.

  • Capture on the external interface: tcpdump -i eth0 udp port 51820 -w wg-external.pcap.
  • Capture on the WireGuard interface: tcpdump -i wg0 -w wg-internal.pcap.
  • Use Wireshark or tshark to inspect handshakes and patterns. WireGuard packets use UDP but are opaque; however, counts and timing indicate activity.

Note: WireGuard encrypts payloads, so you won’t see decrypted traffic unless you capture pre-encryption on the WireGuard interface.

Systemd, scripts, and automation gotchas

When you use automation or systemd to bring up interfaces, ensure the environment has the expected state:

  • wg-quick’s PostUp/PostDown scripts run as root; confirm they succeed and do not exit early. Check service logs with journalctl -u wg-quick@wg0.
  • If interfaces are created before network is ready in cloud-init or early boot, systemd units may fail. Use proper dependencies (After=network-online.target).
  • When using containers or virtualized hosts, ensure network namespaces are applied correctly and peer endpoints reference reachable addresses.

Common failure scenarios and fixes

  • No handshake ever: Confirm firewall/NAT rules permit UDP to the server and the correct port is used. Verify public keys and endpoint IP/port.
  • Handshake but no traffic: Check AllowedIPs on both ends, IP forwarding, and NAT rules. Ensure route selection sends traffic into the tunnel (ip route get).
  • Intermittent connectivity: Look for MTU issues, mobile NAT timeouts, or packet drops due to firewall state timeouts. Increase persistent keepalive (e.g., 25s) for peers behind NAT.
  • Slow throughput: Profile CPU, disable problematic NIC offloads, and tune MTU/MSS. Ensure encryption is using hardware acceleration if available (e.g., AES-NI).
  • DNS leaks or failures: Ensure DNS is reachable via tunnel and that client resolver configuration points to your intended DNS server.

Advanced tips and tools

Use these advanced techniques for persistent or complex issues:

  • Enable debug logs by starting wg-quick with WG_QUICK_USERSPACE_IMPLEMENTATION=userspace /usr/bin/wg-quick up wg0 for additional output, or add LogLevel=debug for system services where applicable.
  • Use conntrack -L to inspect connection tracking entries that might affect NATed sessions.
  • For clouds, check security group rules and host-level firewall settings separately; cloud-level blocking can be invisible from the instance.
  • Consider using a monitoring agent to alert on “latest handshake” ages or transfer counter stagnation so you can proactively detect peer problems.

Checklist to run through on any outage

  • Is the WG interface up? (ip link show)
  • Are keys and public endpoints correct? (wg show)
  • Are UDP packets reaching the server? (tcpdump, nc -u)
  • Are firewall/NAT rules permitting traffic and forwarding enabled?
  • Are AllowedIPs and system routes as intended? (ip route, ip rule)
  • Is MTU causing fragmentation issues? (Ping with -M do)
  • Do transfer counters increase? Are handshakes recent?

WireGuard’s elegance means there are fewer moving parts than traditional VPNs, but the parts that remain — keys, routing, firewall, NAT, and MTU — must all align. Methodical diagnostics using the commands and checks above will get you to the root cause rapidly.

For more resources and guides on configuring and optimizing VPNs, visit Dedicated-IP-VPN at https://dedicated-ip-vpn.com/. Dedicated-IP-VPN provides detailed documentation and best practices for production-grade VPN deployments.