Troubleshooting

When troubleshooting connection issues, first determine whether the failure occurred at the domain layer or the resource layer.

Domain Connection Failed

### WireGuard

Check:

• Whether the peer address and port are correct.
• Whether the local private key, peer public key, and preshared key match.
• Whether the local IP includes a CIDR suffix.
• Whether the server allows this peer.
• Whether the server allows forwarding to the target internal network.

FRP

Check:

• Whether serverAddr and serverPort are correct.
• Whether the token matches.
• Whether transport.protocol matches what the server supports.
• Whether user and clientID conflict with other online clients.

If frps reports client_id is already online, it means the same user/clientID is already connected.

### Tailscale

Check:

• Whether you are logged in.
• Whether the device has been authorized by the Tailscale or Headscale admin console.
• Whether the control server URL is correct.
• Whether the Auth Key is valid.
• Whether the current network can access the control server.

If there is no login link, first check whether Headscale supports interactive login, or try using an Auth Key instead.

ZeroTier

Check:

• Whether the Network ID is correct.
• Whether the new device appears in the ZeroTier console.
• Whether the new device has been authorized.
• Whether the current network allows ZeroTier connections.

Resource Connection Failed

Web page won't open

Check:

• Whether the URL includes http:// or https://.
• Whether the resource belongs to the correct domain.
• Whether the target host and port are reachable from that domain.
• Whether the HTTP page is being blocked by App Transport Security or a mixed content policy.

HTML loads but page functionality is abnormal

Ajax, WebSocket, or redirect URLs may not be routing correctly. Check whether the actual request addresses in the page are still within the reachable range of the current domain.

SSH stuck on connecting

Check:

• Whether host, port, and username are correct.
• Whether the current domain is ready.
• Whether the target sshd allows connections from the domain address.
• Whether the authentication method is correct.
• Whether the private key requires a passphrase.

File manager blank or cannot open directory

Check:

• Whether the FTP / SMB / SFTP / WebDAV credentials are correct.
• Whether the path is an existing directory on the server.
• Whether the SMB path includes the share name.
• Whether the local directory has been authorized through the system file picker.

VNC connection failed

Check:

• Whether the port is correct, commonly 5900 or 5901.
• Whether the server has VNC password auth enabled.
• Whether the password is correct.
• Whether the server uses an advanced security type or encoding that OmniGate does not yet support.

Resource becomes invalid after switching apps or locking the screen

Mobile systems may suspend background connections. After OmniGate enters the background, all domain connections are automatically disconnected after the configured timeout (default 5 minutes) to save battery. When returning to the foreground, domains with auto-connect enabled will automatically come back online.

If a resource cannot recover:

1. First, use the resource page menu to reconnect.
2. If that fails, go back to the resource list and reopen the resource.
3. If the domain status is abnormal, switch domains or restart the app.

If you want to maintain connections in the background without disconnection, select "Never disconnect" in Settings > General > Background Connection Timeout, but be aware that this will increase battery consumption.

Resource becomes invalid after switching networks

After switching Wi-Fi networks, switching to cellular data, or reconnecting to the network, OmniGate automatically detects the network change and reconnects domains that are currently in use or have auto-connect enabled.

If auto-reconnect does not take effect:

1. Check whether the corresponding domain's status in the domain list has recovered to connected.
2. Use the resource page menu to reconnect.
3. If that fails, go back to the resource list and reopen the resource.

## How to Read Logs

When debugging, first look for the following keywords in the Xcode console:

• [ProxyRuntime]
• [Browser]
• [SSH]
• [WireGuardProxy]
• [TailscaleProxy]
• [ZeroTierProxy]
• [FRP]
• [SOCKS5]

Diagnostic principles:

• If there are only domain logs and no resource logs: the resource may not have started connecting yet.
• If the domain is ready but the resource fails: first check the target address, port, and authentication.
• If "direct mode" appears: verify whether the resource belongs to a None domain, or whether the current proxy is not activated.