Skip to main content

Common issues

Find the problem that matches your symptoms and open it for the fix.

Connected, but no internet (or unstable)#

The VPN reports a connected state, but internet access is missing or drops in and out.

Symptoms

  • The client status shows "Connected", but web browsers display timeout errors.
  • Internet routing functions intermittently or drops completely every few minutes.
  • IP verification websites (e.g. ifconfig.me, icanhazip.com) fail to load.

Resolution steps — macOS and Linux with GUI

  1. Switch exit nodes: click the location dropdown and select an alternative node with the lowest available latency (ms).
  2. Verify wallet balance: click the wallet icon in the top-right corner. Ensure your account balance is sufficient; top up if it is depleted.
  3. Hard restart: completely terminate the application. Right-click the Gnosis VPN tray icon, select Quit, and relaunch the application.

Resolution steps — Linux without GUI

  1. Check your node and wallet status — verify your Safe and channel balances with your active exit node: 
    gnosis_vpn-ctl balance
  2. If your balance is sufficient, restart the background service to flush stuck routing tables: 
    # Linux
    sudo systemctl restart gnosisvpn.service

    # macOS
    sudo launchctl kickstart -k system/com.gnosisvpn.gnosisvpnclient
Connection handshake takes over 60 seconds#

The client hangs indefinitely in a "Connecting" state when attempting to establish a tunnel with an exit node.

Symptoms

  • The interface or terminal status stays frozen in the connecting phase for over 1–2 minutes.
  • Specific geographic locations fail to hand over traffic, while others connect instantly.
  • Connection eventually succeeds, but only after an unacceptable delay.

Resolution steps — macOS and Linux with GUI

  1. Click the wallet icon to verify your account balance.
  2. Pick an alternate exit node with lower latency.
  3. Restart the app via the tray icon menu if it remains frozen.

Resolution steps — Linux without GUI

  1. Inspect the handshake state: 
    gnosis_vpn-ctl status
  2. Force a reconnection to a different node endpoint: 
    gnosis_vpn-ctl connect --node <alternative_node_id>
App looks too big, too small, or incorrectly scaled (Linux)#

The Gnosis VPN app is built on GTK3, which runs through the legacy X11 compatibility layer on Wayland. This can cause incorrect scaling when display scaling is set manually.

Resolution steps

Find the scaling option for legacy (X11) apps in your desktop environment's display settings and set it to "Scaled by the system".

On KDE, this is typically found under Display Configuration:

KDE legacy X11 app scaling setting

Critical error during initialization after updating#

The client fails to start after an update and shows Critical error during initialization. This happens when you have used an earlier release of Gnosis VPN: the latest release runs on a different network, but your machine still holds the identity created on the old one. The safe belonging to that identity does not exist on the new network, so startup fails and retries in a loop.

Symptoms

  • The app shows Critical error during initialization, with a construction or chain error mentioning the network endpoint.
  • Syncing appears to resume on its own, then the same error returns shortly after.
  • The service log repeats the same failure every 10 seconds: 
    INFO  hopr_lib::builder: registering safe with this node safe_addr=<safe_address>
    ERROR hopr_lib::builder: safe registration failed safe_addr=<safe_address> error=safe registration error: safe <safe_address> does not exist
    WARN  hopr_chain_connector::connector: chain subscription stream ended, marking chain health as degraded
    ERROR gnosis_vpn_lib::hopr::api: error=Construction error: chain error: safe registration error: safe <safe_address> does not exist
    ERROR gnosis_vpn_lib::core: hopr runner failed to start - trying again in 10 seconds

Resolution steps

Resetting the client means backing up the identity, removing the original, and letting the client generate a new one on the current network.

warning

These steps discard the identity the client is currently using. Complete the backup and confirm it exists before running the removal command — the backup is what lets support restore your previous identity if it is ever needed.

  1. Stop the service: 
    sudo launchctl bootout system/com.gnosisvpn.gnosisvpnclient
  2. Back up your current identity. The backup is written next to the identity, not inside it, so the next step cannot delete it: 
    sudo cp -a /Library/Application\ Support/GnosisVPN/.config /Library/Application\ Support/GnosisVPN/.config.backup
  3. Confirm the backup exists before continuing: 
    sudo ls -la /Library/Application\ Support/GnosisVPN/.config.backup
  4. Remove the current identity: 
    sudo rm -rf /Library/Application\ Support/GnosisVPN/.config
  5. Start the service again: 
    sudo launchctl bootstrap system /Library/LaunchDaemons/com.gnosisvpn.gnosisvpnclient.plist

The client generates a new identity on the current network at the next start. This is a fresh account, so you need to fund it before you can connect — see Funding your account.

Still not working?​

If the steps above don't resolve it, attach your client logs to your support ticket. See Finding your logs and Reporting issues.