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 Aether: closing with reason:.
Each connection message below was produced by a case of Test results, and the server's side of each comes from the server's log in the same run. The import's messages are the editor's, read from the source code of both apps.
First checks
- Open the connection log: tap the status under the power button. Its first lines name the mode, the transport, the endpoint scan and the options. Set Log Level to Expert to see a line for each test connection that went through, with the session's age and the bytes that went each way.
- In Private mode, on the server:
wg show wg0lists each phone with itslatest handshake; a phone without one has never reached the server with the right keys.docker logs --tail 20 aethershows whether the engine has its tunnel to WARP, and thecurlof the server guide's check tests it from the server itself.
Public mode
| Message | What it means and what to do |
|---|---|
| Aether: no reachable MASQUE endpoint or the tunnel data-plane did not come up | No WARP edge carried traffic. In our Android run with Turbo, the first edge that answered took the request but carried no traffic. The app makes one attempt before the first connection, so connect again, set Retry Times, or use Balanced, which compares more edges. If it keeps happening, the network may block MASQUE: try MASQUE (HTTP/2), with TLS Fragmentation if needed. |
| The WARP session ended (auto reconnect is off). | The engine's tunnel to WARP ended while the VPN was up. With Auto Reconnect on, the app sets up a new session instead. |
Private mode
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, so its message names every cause; wg show wg0 and the keys in the file show which one it is.
| Message | What it means and what to do |
|---|---|
| Aether private: 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 51820 may be closed. | No answer to the handshake within 30 seconds. Check that the file is this phone's and still on the server (a removed phone gets this message), that the server's public key in it is the server's, and that the server's UDP port is open and is the one in the profile. |
| Aether private: the server answers over WireGuard, but its Aether proxy (port 1819 on 10.66.66.1) refused the connection: is the aether container running? | WireGuard works, but nothing listens on the engine's port. Start the container (docker start aether) and check its log; the server guide publishes the port on wg0's address. |
| Aether private: 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. |
| Aether private: Invalid WireGuard config: a key is not valid base64 (32 bytes). | A key in the file is damaged: a key is 44 characters of base64 ending in =. Copy it again, without spaces or line breaks, or make the phone's file again. |
| Aether private: The config has no [Interface] Address. | A line the app needs is missing from the file. Make the phone's file again with add-phone.sh. |
| The server stopped carrying traffic: two test connections through it failed (auto reconnect is off). | The connection was up, then two test connections in a row failed: the server, its WireGuard port or the path to it went away. With Auto Reconnect on, the app connects again once the server is back. |
The phone's file
| 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. |
| This file has AmneziaWG settings (… and others). Aether's Private mode takes a WireGuard file. | An AmneziaWG file: the server of Private mode speaks plain WireGuard. Import the file add-phone.sh made. |
Retry Times and sleep
| Message | What it means and what to do |
|---|---|
| Could not connect after 3 attempts. (…) | Before the first connection, every attempt failed: one, plus the two of Retry Times. The reason in brackets is the last attempt's. |
| Could not reconnect after 2 attempts. (…) | The connection was lost, and Retry Times ran out before a new session worked. |
| The connection was closed while the device slept. | On Sleep is Off and Auto Reconnect is off: the app closed the session for sleep and did not connect again at wake. Choose Pause or Stay, or turn Auto Reconnect on. |