Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Desktop Client connectivity issues

Overview

This guide provides instructions for troubleshooting common network connectivity issues that can be encountered when using WireGuard VPN clients to access VPN-protected resources.

Preparing for testing

Before beginning connectivity tests, ensure:

  • Disable ACLs and MFA for the VPN location being tested

  • Temporarily disable firewall rules dropping ICMP traffic on the gateway server

Remember to restore the original settings after you conclude your testing.

This way we remove additional factors and can check if the basic VPN connection is configured correctly.

VPN Gateway Public IP

First, verify basic network connectivity to the gateway's public IP:

ping <GATEWAY_PUBLIC_IP>

Cloud providers such as AWS, GCP and Azure often block ICMP in security groups by default. If the gateway runs in the cloud, a failed ping does not by itself mean the gateway is unreachable. Allow ICMP temporarily for this test, or skip to the next step.

Troubleshooting if IP is unreachable:

  • Verify the IP address is correctly configured in location settings

  • Verify your gateway-side firewall rules don't block traffic from the internet

  • Check client-side firewall rules if you use them

VPN Connection Test

If the public IP is reachable, attempt to connect using the VPN client:

  • Initiate connection to the VPN location

  • If errors occur, check client logs for detailed information

  • Verify that the endpoint the client uses matches the gateway address and gateway port in location settings. With the WireGuard CLI installed, run wg show on the client machine and compare the endpoint value. If the location settings were changed after the device was added, reconnect so the client fetches the current configuration.

Check the gateway

While a client is trying to connect, check whether the gateway sees the handshake. This tells you whether the client's packets reach the gateway at all.

Docker:

Package or binary installation:

Look for the client's peer (identified by the device public key) and its latest handshake and transfer values:

  • No latest handshake: packets from the client do not reach the gateway's WireGuard interface. Check the port mapping and firewall rules described below.

  • Handshake present, transfer only growing in one direction: the tunnel works, so the problem is routing or firewall rules on the gateway. See Can access VPN but not local network or internet.

Also check the gateway logs for errors applying the configuration received from Core:

Docker port mapping

When the gateway runs in a Docker bridge network (the default in the one-line install script), the published UDP port must match the gateway port set in location settings. The gateway listens on the port configured in the location, not on a port set in the Compose file. The example Compose files publish 51820:51820/udp. If your location uses a different port, for example 1194, change the mapping to "1194:1194/udp" and use the same number on both sides.

If you migrated a one-line installation from Defguard 1.6, the old host-network gateway may have left a WireGuard interface and firewall state on the host that intercepts VPN traffic. See Clean up 1.6 host networking.

VPN Network Connectivity

Once connected to a VPN location, test internal VPN connectivity by trying to ping the Gateway internal IP configured in location settings:

Example: If your VPN subnet is 10.0.10.0/24, the gateway is typically 10.0.10.1

If you have the official WireGuard CLI installed you can also verify the VPN connection by checking for the latest handshake. If there's no handshake, a connection has not been established.

If gateway is unreachable within VPN subnet:

  • This indicates WireGuard connection failed to establish

  • Client will automatically disconnect after 5 minutes (300 seconds) if no WireGuard traffic is detected (this threshold is configurable in client settings)

  • This might indicate that the VPN server is not allowing UDP traffic on the specified port

  • Check if the firewall is configured correctly to allow UDP traffic on the selected port

Verify UDP Port Connectivity

If you want to explicitly test if UDP traffic is allowed between the client and VPN server you can do the following:

Stop the gateway before running this test, because socat cannot listen on a port the gateway already uses. With Docker, also stop the gateway container (docker compose stop gateway), since Docker holds the published port on the host. A successful test proves that UDP traffic reaches the host, but not that Docker forwards it into the gateway container. Start the gateway again afterwards.

  • start a test UDP server on the gateway server:

  • send a message from a client machine:

  • if UDP traffic is allowed, a message should appear in your server terminal

Port scanners such as nmap -sU cannot confirm that a WireGuard port is reachable. WireGuard does not respond to packets that are not a valid handshake, so a scanner cannot tell an open port from a filtered one. Use the socat test above or check for a handshake on the gateway instead.

Loss of connection after network change

The connection to the VPN network may stop working if your internet network has changed while the connection was active (for example if you switched Wi-Fis). This can be resolved by simply re-connecting to a given VPN location.

DNS Configuration Issues

If the VPN connection establishes, but you still cannot access VPN-protected resources it can sometimes mean there's an issue with the DNS server configured for a given VPN location.

To verify DNS functionality:

  • Check if DNS configuration in location settings is correct

  • Test DNS resolution for the resources you're trying to access

DNS Testing Commands:

Linux:

macOS:

Windows:

Troubleshooting DNS Issues:

  • Verify DNS server IP addresses in location settings

  • Test with different DNS servers (e.g., 8.8.8.8, 1.1.1.1)

  • Verify there are no firewall rules on your gateway server which would block DNS access

MTU Issues

If VPN connects but you cannot access certain resources, another possible cause is an invalid MTU configuration of the network interface.

By default WireGuard uses an MTU of 1420 bytes, but some ISPs may limit packet size.

To test MTU limits: Linux:

Windows:

You can try to lower the packet size until the ping command succeeds to find the limit.

Workaround:

  • Set a lower MTU value manually for the WireGuard interface created by the client

PreviousClient crashes immediately on launch with "Error 71 (Protocol error) dispatching to Wayland display"
NextMobile Client

Last updated

Was this helpful?