Verify the Download Before Troubleshooting Installation Errors
The file extension determines what to do next. Run Windows EXE files with the installer; extract ZIP files first. Mount macOS DMG files. Install Android APK files with the system installer. Use the appropriate package manager for Linux DEB and RPM files. If your browser saved a webpage instead, or the download is still in progress, renaming the file won’t turn it into an installer. Confirm you have the expected file format before troubleshooting the specific error.
Keep Your Original Configuration and Stop the Old Client Before Migrating
Before reinstalling, save your subscription source, custom rules, and overrides. Subscription links may contain personal credentials, so don’t include them in public screenshots or support logs. When switching clients, quit the old app and confirm its system proxy and VPN session are disabled before launching the new one. If the new client won’t run, you can revert to the old setup and compare settings one by one.
Use One Connection Mode at a Time on First Run
First, make sure the configuration loads. Then choose a policy group and proxy mode. On desktop, test the system proxy first; try TUN only if you need it. If a browser works but a desktop app doesn’t, check whether that app uses the system proxy before reinstalling. If the configuration won’t parse, start with the first error and check field hierarchy, indentation, and core support. See the Getting Started guide for detailed steps, and the configuration field reference for field definitions.