Unable to Connect: Host Configuration for WireGuard Tunnel

Resolve WireGuard connection failures by verifying that the public keys match between client and server configurations, ensuring the ListenPort is open in your firewall, and confirming that AllowedIPs correctly route traffic. Misconfigured endpoints or mismatched cryptographic identities are the most common causes of immediate handshake timeouts.

Verify Cryptographic Identity

The most frequent reason for a "Handshake failed" or persistent connection timeout is a mismatch in the public keys. WireGuard relies on pre-shared keys to establish a secure tunnel, and even a single character error will prevent the peers from recognizing each other. You must ensure that the PublicKey listed in the client’s configuration matches the PublicKey generated on the server side, and vice versa. To verify this, generate a new key pair on the machine where you suspect the error lies using the command line tool wg genkey. Pipe the output to wg pubkey to display the public key. Compare this output strictly with the value present in the peer’s configuration block on the opposite end. Do not rely on copy-pasting from visual interfaces if possible; use the terminal to ensure no hidden characters are introduced. If you have recently regenerated keys, remember that the old private key becomes invalid immediately, breaking the tunnel until all peers are updated. For more details on resolving key mismatches, see our guide on Wireguard Issue on Home WiFi - Troubleshooting Guide.

Check Endpoint and Port Configuration

Even with correct keys, the tunnel cannot establish if the network path is blocked or misdirected. The Endpoint field in the client configuration must point to the exact IP address and port where the server is listening. This should be the public IP address of the server if connecting over the internet, or the local IP if connecting within a LAN. The ListenPort on the server defines which UDP port accepts incoming connections, typically 51820. You must ensure that your router’s firewall or cloud provider’s security groups allow inbound UDP traffic on this specific port. If the server is behind a NAT device, port forwarding must be configured to direct traffic from the external port to the internal IP of the WireGuard host. A common mistake is setting the endpoint to localhost or 127.0.0.1 on the client; this will only work if the client and server are running on the same machine, which is rare for tunnel setups. Use netstat -ulnp | grep wg or ss -ulnp | grep wg on the server to confirm that the WireGuard process is actually bound to the expected interface and port. If the service is not listening, start it with systemctl start [email protected] and check for errors in journalctl -u [email protected].

Validate AllowedIPs and Routing

The AllowedIPs directive serves a dual purpose: it specifies which traffic is encrypted through the tunnel and acts as the routing table for the virtual interface. If this field is empty or incorrectly set, packets may not reach the remote network, or worse, they may leak out unencrypted. For a standard site-to-site or remote access setup, the client’s AllowedIPs should include the subnet of the remote network (e.g., 192.168.4.0/24) or 0.0.0.0/0 for full tunneling. On the server side, the AllowedIPs for each client peer must define the range of IPs assigned to that client. If you are experiencing issues where the connection seems established but there is no internet access, review how split tunneling is handled. Incorrect routing tables can cause default gateway conflicts, dropping all non-local traffic. Refer to Bypass/split tunnel wireguard for strategies on managing traffic flow selectively. Ensure that IP forwarding is enabled on the Linux host acting as the server. Run sysctl net.ipv4.ip_forward; if it returns 0, enable it with sysctl -w net.ipv4.ip_forward=1. Additionally, verify that iptables or nftables rules permit masquerading or NAT for traffic leaving the VPN interface, otherwise return traffic from the internet will not know how to find the client behind the tunnel.

Debugging Connection States

When basic checks pass, use the wg show command to inspect the live state of the tunnel. Look at the Latest Handshake timestamp. If it updates frequently, the connection is healthy. If it remains static while you attempt to send data, the handshake is failing. Check the RxBytes and TxBytes counters; zero values indicate no packet exchange. Enable verbose logging on the server by adding LogLevel = debug to the [Interface] section of the configuration file. Restart the service and monitor journalctl -f -u [email protected]. This will reveal if packets are being dropped due to policy violations, key mismatches, or source address verification failures. Remember that WireGuard does not perform traditional authentication beyond the cryptographic handshake; any successful handshake implies valid credentials.

Frequently Asked Questions

Why does my WireGuard connection drop randomly?

This often occurs due to NAT timeout settings on intermediate routers clearing the UDP session state. Configure the PersistentKeepalive option in the client config to send periodic keep-alive packets, preventing the connection from timing out. Setting it to 25 seconds is a common default for mobile clients moving between networks.

Can I use WireGuard with IPv6 only?

Yes, WireGuard fully supports IPv6. Ensure that both the PrivateKey and PublicKey are generated correctly for your environment, and set the Address field to a valid IPv6 prefix. The Endpoint must also be an IPv6 address if the server is reachable via IPv6 only.

What causes 'No response' errors during handshake?

This usually indicates a firewall blocking UDP traffic or an incorrect endpoint IP/port combination. Verify that the server’s firewall allows inbound UDP on the listen port and that the client’s endpoint points to the server’s public-facing IP address, not its private LAN IP.

How do I reset a WireGuard configuration without losing keys?

You can edit the configuration file directly using a text editor like nano or vim without regenerating keys. After saving changes, restart the service with systemctl restart [email protected] to apply the new settings while retaining the existing cryptographic identity.

Is it safe to share my WireGuard configuration file?

No, never share the configuration file containing your PrivateKey. Anyone with access to the private key can impersonate you and decrypt your traffic. Only share the public key and the server’s endpoint information when granting access to new peers.