General troubleshooting steps

Try these in order, regardless of your platform. Most issues are resolved by one of these steps:

  1. Force-close and reopen the app
  2. Restart your device
  3. Update the app to the latest version from the app store or happ.su
  4. Clear app data (this removes your subscription, so have your link ready to re-add)
  5. Reinstall the app from scratch
  6. Try a different VPN client (switch from Happ to v2RayTun, or vice versa)

Platform-specific fixes

Android

App freezes or stops responding:

  1. Go to Settings > Apps > Happ (or v2RayTun) > Force stop
  2. Clear cache: Storage > Clear cache (do not clear data unless you want to re-add your subscription)
  3. If crashes persist, uninstall and reinstall from the Play Store or happ.su

App keeps closing in the background:

Some Android phones (Xiaomi, Samsung, Huawei) aggressively kill background apps to save battery. This causes the VPN to disconnect.

  1. Go to Settings > Apps > Happ > Battery
  2. Change battery optimization to “Don’t optimize” or “Unrestricted”
  3. On Xiaomi: Settings > Apps > Manage apps > Happ > Battery saver > “No restrictions”
  4. On Samsung: Settings > Apps > Happ > Battery > “Unrestricted”

Will not start after an update:

  1. Uninstall the app
  2. Restart your phone
  3. Reinstall from the Play Store

iOS

App crashes on launch:

  1. Delete and reinstall from the App Store
  2. If using the TestFlight version of Happ, make sure your TestFlight build has not expired. Check the TestFlight app for updates

VPN toggle will not turn on:

  1. Go to Settings > General > VPN & Device Management
  2. Delete any old VPN profiles listed there
  3. Open the app and reconnect. Tap Allow when iOS asks for VPN permission
  4. Enter your passcode when prompted

Windows

Happ or v2RayTun will not open:

  1. Check the system tray (bottom right corner of the taskbar). The app may be running minimized
  2. If you see it in the tray, right-click and choose Show window
  3. If not, open Task Manager (Ctrl+Shift+Esc), find the app process, end it, and relaunch
  4. Try running the app as Administrator (right-click the app > Run as administrator)

Blank or white window:

  1. Update your graphics drivers
  2. Try running the app in compatibility mode (right-click > Properties > Compatibility > Windows 8)

“Missing DLL” error:

  1. Install the latest Visual C++ Redistributables
  2. Make sure Windows is fully updated (Settings > Windows Update)

“TAP driver failed” error:

  1. Re-run the app installer as Administrator
  2. If that fails, uninstall the app, restart Windows, and reinstall

macOS

“App is damaged and cannot be opened” warning:

This is a macOS security false positive for apps not distributed through the App Store.

  1. Right-click the app and choose Open
  2. If that does not work, go to System Settings > Privacy & Security and click Open Anyway
  3. You may need to enter your Mac password to confirm

System extension or network extension will not load:

  1. Go to System Settings > General > Login Items & Extensions > Network Extensions
  2. Make sure Happ (or v2RayTun) is toggled to Allowed
  3. You may need to restart your Mac after enabling the extension

App opens but will not connect:

  1. Make sure no other VPN app is running
  2. Check System Settings > Network and remove any leftover VPN interfaces
  3. Restart the app

Linux

Happ .deb / .rpm will not install:

# For .deb on Debian/Ubuntu:
sudo dpkg -i Happ.linux.x64.deb
sudo apt-get install -f   # fixes missing dependencies

# For .rpm on Fedora:
sudo rpm -i Happ.linux.x64.rpm

# For .pkg.tar.zst on Arch:
sudo pacman -U Happ.linux.x64.pkg.tar.zst

AppImage will not launch:

chmod +x Happ-*.AppImage
./Happ-*.AppImage

If you see a FUSE error:

# Ubuntu/Debian
sudo apt install libfuse2

# Fedora
sudo dnf install fuse

# Arch
sudo pacman -S fuse2

Permission denied when connecting:

The VPN needs root access to modify network routing. Run the app with sudo, or add your user to the network group:

sudo usermod -aG netdev $USER

Log out and log back in for the group change to take effect.

How to collect crash logs

If the app crashes consistently and you need to send us a report:

  • Windows: Press Win+R, type eventvwr, go to Windows Logs > Application, search for the app name
  • macOS: Open the Console app (in Applications > Utilities), search for the app name
  • Android: Settings > Developer options > Bug report (developer options must be enabled first)
  • iOS: Settings > Privacy & Security > Analytics & Improvements > Analytics Data

Send the logs to support@sericavpn.com along with a description of what you were doing when the crash occurred.