Troubleshooting
When a connection fails, the app shows Connection Failed with one of the messages below; when a connection that was up ends, the connection log has the message in a line that starts with WireGuard: closing with reason:.
Each message below was produced by a case of Test results, on both phones, and the server's side of each comes from the server's log in the same run. The first one, the import's, is the editor's: the apps' unit tests check that it refuses such a file.
First checks
- Open the connection log: tap the status under the power button. Set Log Level to Expert to see, every 30 seconds, how long ago the last handshake was and how much came and went.
- On the server,
wg show wg0lists each phone with itslatest handshake. A phone without one has never reached the server with the right keys.
Why WireGuard says so little
A WireGuard server answers nothing to a handshake it cannot take: one from a key it does not know, with the wrong preshared key, for another server key, or on a port where nothing listens. To the app all of these look the same, a server that does not answer, so its message names every cause; the server's peer list and the keys in the files show which one it is.
The configuration
| Message | What it means and what to do |
|---|---|
| The file does not look like a WireGuard config (no [Interface]/[Peer] sections). | The imported file is not a wg-quick configuration. Import the .conf file the server made for this phone. |
| Invalid WireGuard config: The config has no [Interface] PrivateKey., … no [Interface] Address. | A line the app needs is missing from the file. Make the phone's file again (add-phone.sh), or enter the value under Manual Configuration. |
| Invalid WireGuard config: a key is not valid base64 (32 bytes). | The private key or the server's public key is damaged: a WireGuard key is 44 characters of base64 ending in =. Copy it again, without spaces or line breaks. |
| Invalid WireGuard config: the PresharedKey is not valid base64 (32 bytes). | The same for the preshared key. |
| The WireGuard endpoint … could not be resolved. | The server's name in Server (or in the file's Endpoint) does not resolve. Check the name, or enter the server's address. |
Connecting
| Message | What it means and what to do |
|---|---|
| The server did not answer the WireGuard handshake: the server's public key or the preshared key may not match, the server may not have this profile's public key as a peer, or UDP port … may be closed. | No answer within 10 seconds. Compare the profile's Server Public Key with the server's server.pub, and its preshared key with the server's for this phone; check that wg show wg0 lists this phone's public key (a removed phone is no longer there); check that the port is the server's ListenPort and open to the phone on every network it uses: a firewall rule that accepts only some addresses leaves out the phone's mobile data. |
| Could not connect after 3 attempts. (The server did not answer the WireGuard handshake.) | The same, after the attempts that Retry Times adds before the first connection. |
A connection that was up
| Message | What it means and what to do |
|---|---|
| The server stopped answering: nothing came back for 30 seconds (auto reconnect is off). | The server, or the path to it, stopped answering while the phone was sending. With Auto Reconnect on, the app tries new handshakes instead. |
| Could not reconnect after 2 attempts. (The server did not answer the WireGuard handshake.) | The server stopped answering and did not answer the attempts that Retry Times allows. Leave Retry Times empty to keep trying while the server is away. |
| The connection was closed while the device slept. | On Sleep is Off and Auto Reconnect is off: the app closed WireGuard when the device slept and does not connect again at wake. Choose Stay or Pause, or turn Auto Reconnect on. |