Clash Verge Crashes on Startup: Troubleshooting and Fixes

First, identify the issue: a crashing window, a background process, or a core that won't start

Clash Verge's interface, proxy core, and system service are separate components. A disappearing window doesn't necessarily mean the whole client has exited. Likewise, if the window opens but the core fails to start, WebView2 may not be the cause. Note your OS version, the client's full version, the installer architecture, and whether the issue began after an update, importing a subscription, or a fresh install.

The original Clash Verge and the later maintained release, Clash Verge Rev, should not be treated as the same version. They may use different data directories, service names, and settings labels. If the interface opens, note the version shown in the About section of Settings. If it doesn't, check the installer filename or executable properties rather than relying on the desktop shortcut name.

1. Check the taskbar notification area. On Windows, show hidden icons; on macOS, check the menu bar.
2. Exit the client, then check Task Manager or Activity Monitor. End only processes you've confirmed belong to the client.
3. Launch it once and note the exact time. Don't double-click repeatedly; single-instance locks and multiple launch records can make diagnosis harder.

Step 1: Check WebView2 and application errors on Windows

The Clash Verge interface on Windows depends on WebView2. Microsoft Edge opening normally doesn't guarantee that the WebView2 Runtime is working. If the main window is blank, WebView2 creation fails, or a crash record points to a WebView2 component, troubleshoot the runtime before changing your subscription repeatedly.

Repair the runtime in this order

1. Exit the client. In Windows 11, open Settings → Apps → Installed apps and search for Microsoft Edge WebView2 Runtime. App listings vary between systems, so not finding it in search alone doesn't prove it's missing.
2. If the entry offers Modify or Repair, follow the prompts. Otherwise, use Microsoft's official Evergreen WebView2 Runtime installer to repair or install it. For offline systems, use the standalone installer for the correct architecture.
3. After installation, restart the client. If the installer requires a system restart, save your work first.
4. If it still crashes, press Win + R, enter eventvwr.msc, then open Windows Logs → Application and look for an error at the time you noted.

An entry from Application Error with Event ID 1000 can be a useful clue, but it won't appear for every crash. Note the faulting application name, faulting module name, and exception code. Seeing only ntdll.dll doesn't prove that system files are damaged; it may simply be where the exception surfaced.

Treat a blank window differently from a crash

If the window is blank but the process remains, preserve the UI logs first, then check the runtime and user data. If the process disappears entirely, also check Windows application error records. Don't apply GPU-disabling launch flags found online to every version: builds may not accept the same flags, and unverified options may have no effect.

WebView2 checks apply to Windows only. macOS uses the system WebKit, while Linux builds typically rely on system components such as WebKitGTK. Installing a Windows runtime won't fix either platform.

Step 2: Check for port conflicts and distinguish proxy ports from the control port

If logs show address already in use or Only one usage of each socket address, check the listening ports first. A port conflict usually prevents the core from starting, but doesn't necessarily crash the interface. If the interface also exits, check its logs separately rather than conflating the two issues.

In the config, mixed-port is the mixed-proxy listener, while external-controller is the control interface. The examples below use 7897 and 9090 for queries; these aren't fixed defaults across all versions. Substitute the actual ports shown in your logs or current config.

Windows: Find the process listening on the port

Get-NetTCPConnection -State Listen -LocalPort 7897,9090 -ErrorAction SilentlyContinue |
  Select-Object LocalAddress, LocalPort, OwningProcess

Get-Process -Id 4321

Run the first command in PowerShell, then replace 4321 in the second command with the actual OwningProcess value. No results only means these TCP ports weren't listening when queried; it doesn't confirm that other core ports are available. Don't terminate a process based on the sample PID.

macOS and Linux: Check what's listening

# macOS
lsof -nP -iTCP:7897 -sTCP:LISTEN
lsof -nP -iTCP:9090 -sTCP:LISTEN

# Linux
ss -ltnp 'sport = :7897'
ss -ltnp 'sport = :9090'

• If another proxy client is using the port, quit it normally from its tray or menu bar, then try again.
• If it's a core left over from a previous launch, verify its path and ownership before stopping it. Avoid terminating another user's process or a service used by other software.
• If you need to change a port, use the port settings supported by the client. If you have override configs, check the effective value too; changing only the original subscription file may not be enough.

When you change the proxy port, update browser extensions, proxy environment variables in your terminal, and any other manual settings. If you change the control port, make sure the client and core use the same address. Don't expose the control interface on 0.0.0.0 just to work around a local issue.

Step 3: Back up user data and isolate a corrupted config

If the issue began right after importing a subscription, editing YAML, or upgrading, focus on the config and local state. Uninstalling often leaves user data behind, so reinstalling may not change what the client reads at startup. Back up your data first, then launch the app with a fresh data directory.

Find the correct directory instead of guessing from the app name

If the interface opens, use the config directory or log directory shortcut in Settings. Labels vary by release, such as Config directory, Open config directory, or App directory. If you can't get in, check the app-specific folders in the locations below, and confirm ownership using modification dates, logs, and the app identifier.

• Windows: Enter %APPDATA% and %LOCALAPPDATA% separately in File Explorer's address bar. Config files and WebView cache may be stored in different locations.
• macOS: In Finder, choose Go → Go to Folder and check the corresponding app folder under ~/Library/Application Support/.
• Linux: Check the app folders under ${XDG_CONFIG_HOME:-$HOME/.config} and ${XDG_DATA_HOME:-$HOME/.local/share}. If you've customized the XDG environment variables, use the actual paths.

Create a clean profile by renaming the existing folder

1. Exit the client and any background processes you've confirmed belong to it. Stop its service first if needed.
2. Copy the entire app config directory to a separate backup location. It may contain subscription URLs, node credentials, and control interface keys, so restrict access.
3. Rename the original config directory and add a recognizable suffix, such as .backup-20261017. Don't delete all of AppData, Library, or .config.
4. Launch the client without importing the old config or enabling TUN, and check whether the main window stays open.
5. If the fresh profile works, import a known-good subscription first, then restore overrides, scripts, and other settings one at a time.

If logs show errors such as yaml: line, unmarshal, or a missing policy name, check the relevant line, field type, and references. YAML uses spaces for indentation; align fields at the same level. Policy groups must reference existing nodes or group names. The client interface opening doesn't guarantee that the current core supports every field in an older config.

Step 4: Check for leftover service mode and TUN permission issues

Service mode lets background components run with the permissions they need, while TUN routes traffic through a virtual network adapter. They're related, but they're not the same setting. If the system proxy works but enabling TUN fails, check the service, permissions, and virtual adapter before reinstalling WebView2.

Restore the standard proxy first, then troubleshoot the service

1. If you can open Settings, turn off TUN first, then use the client's service management controls to stop or repair the service. The exact buttons vary by version.
2. On Windows, press Win + R and enter services.msc. In the Properties of a candidate service, check the executable path to see whether it points to an old install location.
3. If an old service remains after an upgrade, use the original client or installer to remove or repair it, then let the current client install its service.
4. After restarting, test the interface and core with TUN off first, then test TUN separately.

Don't run sc delete based only on a similar display name, and don't remove virtual adapters in bulk. A stale service path, a service that won't start, and a routing conflict are separate issues. Administrator privileges may fix some permission problems, but won't repair a corrupted config or a port conflict.

On macOS, check the executable path for background helpers; on Linux, check systemd service paths. If a service file belongs to another client you still use, leave it alone. Work devices may also be subject to network policies, so check device management requirements first.

Step 5: Check security software logs instead of disabling protection globally

If the client worked yesterday but won't open today, a program update, quarantined core file, or changed security policy may be involved. In Windows, open Windows Security → Virus & threat protection → Protection history and check for client, core, or helper service files at the time of the crash.

• Note the full path of the file that was blocked or modified, the detection name, and the time. A desktop icon still being present doesn't prove the program files are intact.
• Make sure the installer came from the project's official release channel. Review the release notes and the signature information provided by your OS; don't restore executables from unknown sources.
• If you've confirmed a false positive, follow your organization's process to submit a review or add a narrowly scoped exception. Don't exclude the entire Downloads or user folder.
• Controlled folder access can also block writes and prevent the app from saving state. Grant access only to a specific program you've verified as trusted.

On macOS, if you see “Apple cannot check it for malicious software” or “app is damaged,” download the official installer for the correct architecture again and review the system's security alert. Don't run commands that remove quarantine attributes in bulk. On Linux, also check executable permissions, system logs, and package dependency errors.

Clean reinstall on each platform: preserve evidence and restore settings in stages

If the checks above don't identify the cause, try a clean reinstall. Save crash logs, version details, and a backup of your user data first, then turn off the system proxy so your browser doesn't keep connecting to a local port that no longer exists. Install a currently supported release for your system, not an arbitrary older build.

Windows

1. Exit the client normally, stop any verified service, then uninstall the app from Settings → Apps → Installed apps.
2. Rename and keep any leftover config folders confirmed to belong to the app. Don't remove the shared WebView2 Runtime.
3. Reinstall the version for your system architecture. If you see a file-in-use or service-still-running warning, clear the leftover process first and restart the system if needed.
4. Don't restore the old config on first launch. Once the interface opens normally, test the subscription, system proxy, and service mode in order, then test TUN last.

macOS

1. Quit the client from the menu bar. Uninstall its helper service using the process supported by the client, then remove the old app from Applications.
2. Back up and rename the corresponding Application Support data directory. Don't clear the entire Library folder.
3. Use About This Mac from the Apple menu to check whether your device has Apple silicon or an Intel processor, then choose the matching installer.
4. If it still crashes, check crash reports in Console and look for a report from the relevant time in ~/Library/Logs/DiagnosticReports/.

Linux

1. Confirm whether the app was installed as a DEB, RPM, or another package format. Uninstall it with the same package manager to avoid duplicate app launchers from multiple sources.
2. Launch the actual executable from a terminal and save the standard error output. Check for missing libraries, display session issues, and permission errors, then install dependencies as required by your distribution.
3. Back up and rename the corresponding XDG data directory, then reinstall. WebKitGTK dependency names vary by distribution and build, so don't reuse an old dependency list from another system.
4. Wait until the standard desktop window is stable before configuring the service and TUN. Don't run the entire graphical client as root just to get the window to open.

After recovery, verify each setting individually

A successful fix means more than just getting the window to appear: the core should keep running, logs should stop repeating errors, and system networking should recover after you exit. Test in the order below. If an issue returns, go back to that step instead of uninstalling everything again.

1. Clean launch: With no old data imported, launch and exit twice. Check that the window, tray icon, and background process behave consistently.
2. Single config: Import a known-good subscription, confirm the config is selected, and check that the core loads successfully.
3. System proxy: Confirm the actual listening port, enable the system proxy, visit a site you use regularly, and check whether the request appears in the connection log.
4. Custom rules: Restore overrides, scripts, and rule sets one at a time. If the issue returns, keep track of the item you just added and the relevant error line.
5. TUN and service: Enable these last, and check for conflicts with other VPNs, virtual adapters, or corporate networking software.

When reporting an issue, include your OS version and architecture, client and core versions, installation method, time of failure, steps to reproduce, whether a clean config works, and relevant logs. Remove sensitive information such as subscription URLs, node addresses, passwords, control keys, and personal paths. A report like “clean config starts, but restoring an override causes a crash” is usually much easier to investigate than “it crashes on startup.”