Clash Keeps Crashing on Launch: How to Diagnose and Fix Startup Issues

First, identify the failure: app crash, core exit, or VPN startup failure

“Clash keeps crashing on launch” can describe three different problems: the app closes, the proxy core stops, or the system fails to establish a VPN session. Note exactly when it happens before changing your config. A website that won’t load, a node timeout, or a failed subscription update does not, by itself, mean the app has crashed.

Start by noting four things: your phone model and OS version, client name and version, core name and version, and the action that triggers the issue. In particular, note whether it started after a subscription update, a client upgrade, or enabling TUN. These details are more useful for troubleshooting than repeated reinstalls.

Step 1: Keep your config and try low-risk fixes

If the app still opens, export your local config and overrides first. Save subscription URLs separately in a trusted, private place; they often contain access credentials, so don’t include them in public screenshots. Confirm you can still access the config source before considering a data reset.

1. Close other VPN apps. This includes firewalls, ad blockers, and packet-capture tools that use the local VPN service. This prevents them from competing for the system VPN tunnel during testing.
2. Force-stop the client. On Android, go to Settings → Apps → See all apps → select the client → Force stop. Menu names may vary slightly by manufacturer.
3. Open it again. If you can reach Settings, temporarily turn off the client’s auto-connect-on-start option and check whether the interface stays stable.
4. Restart your phone if needed. After restarting, leave other VPN apps closed and launch only the client you’re testing to reduce interference from other services.

Step 2: Check YAML syntax and the subscription response

If the problem started right after a subscription update or rule change, check config parsing first. Well-behaved clients usually report config errors, but some may exit while handling invalid input. Don’t stop at the final “service stopped” message; look earlier in the log for the first parsing error.

Find the issue by searching log keywords

• yaml, unmarshal, line: Check indentation, data types, and the lines around the reported location. The actual error may be on the line just above the one mentioned.
• proxy not found or a policy reference error: Check that every policy group referenced by a rule exists, and that names match exactly, including capitalization and spaces.
• unsupported, unknown: Check whether the log points to a protocol, rule type, or field, then verify that your core supports it.
• The downloaded content starts with <html: You may have received a login page, error page, or access-verification page instead of a config file.

Use spaces—not tabs—for YAML indentation. Quote names or strings containing special characters such as colons or hash marks when necessary. A subscription URL opening in a browser doesn’t guarantee that it returns a Clash config; some subscription formats contain only an encoded node list and require a provider-supplied URL for the right format.

Isolate the problem with a minimal config

If your client can import local YAML, create a temporary config for testing instead of overwriting your only copy. The example below checks basic parsing and core startup only; it contains no proxy nodes and cannot forward traffic. Mobile clients may generate additional VPN, DNS, or TUN settings, so follow the import instructions for your specific client.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
proxies: []
proxy-groups: []
rules:
  - MATCH,DIRECT

7890 is the local mixed-proxy listening port in this example, not a remote node port; a mobile client may override it. If the minimal config starts but your original doesn’t, restore policy groups, rule providers, and overrides one at a time. Test after each addition so you can pinpoint the cause.

If your config comes from a subscription, make fixes through a supported client override or ask the config provider to update the source. Direct edits to a downloaded config may be overwritten the next time it updates.

Step 3: Check the client core against your config features

Clash is a common name across projects and config ecosystems; it doesn’t mean every client with Clash in its name uses the same core. The Clash Meta branch continued development under the name mihomo, with a feature set that differs from the original Clash. Two clients that look alike may support different protocols, rule fields, and TUN implementations.

If the crash started after a config update, check the new features first

For example, an older core may not support a newly added protocol, an extended rule-providers option, or a particular DNS setting. Unknown fields may be ignored or may fail validation; don’t assume that “no error” means a setting took effect. Check the documentation for your core version and the actual logs.

1. Note the app version and core version separately from the client’s About or core information screen.
2. Check the field or protocol named in the error against the core’s documentation to confirm it’s supported.
3. If you need to upgrade, choose a stable release officially published for that client and keep a copy of your config first.
4. After upgrading, start with a minimal config, import the full subscription, then restore your local overrides.

Match the Android installer to your device architecture

Common Android architectures such as arm64-v8a and armeabi-v7a are different; emulators may use x86_64. An architecture mismatch usually causes an installation error, but a missing compatible native library can also cause problems at startup. A 64-bit-capable processor alone doesn’t mean the system supports every 64-bit app. Choose the package specified for your client and device OS.

If the issue clearly began after an app upgrade, save the logs and check the project’s known issues. Downgrading isn’t a universal fix: a newer version may have saved data in a format an older version can’t read, and the older package may not install over it. Don’t repeatedly install over the app using packages from different sources.

Step 4: Work through cache, resources, and app data—in that order

A corrupted cache, interrupted rule-set download, or local database issue can cause repeated startup failures. Start with the least disruptive fix. On Android, go to Settings → Apps → select the client → Storage & cache → Clear cache, then restart the app.

If the app opens, rebuild only the affected resources first

• If the log names a specific rule provider, update or temporarily disable that rule-providers entry instead of deleting every subscription.
• If the log specifically reports a geodata read error, use the client’s resource update option and make sure the download finishes before restarting.
• If you see a storage-space or file-write error, check how much free space is available before trying again. This helps prevent another incomplete file from being created during an update.

Clearing the system cache may not remove a database or config resource saved by the client; it depends on where the app stores its files. If clearing the cache makes no difference, return to the logs instead of repeating the same step.

If you must clear data, restore things in stages

1. Make sure you have backups of your subscription URL, local rules, and essential settings, and that you can retrieve them again.
2. Choose Clear storage or uninstall and reinstall the app. Uninstalling an Android app usually deletes its local app data too.
3. After opening the app for the first time, confirm it stays stable in its clean state. Don’t restore the entire old backup right away.
4. Import one config and test startup. If it works, restore overrides and other subscriptions one at a time.

If restoring the full backup brings the problem back, the restore likely reintroduced the trigger. Check the backed-up config, resource references, and app settings instead of continuing to blame an installation failure.

Step 5: Check VPN permissions, TUN, and background restrictions

Android phones typically use the system VPN service to route device traffic. You generally don’t need root for this. However, mobile clients don’t handle TUN exactly like desktop clients, so don’t copy desktop interface names, routing parameters, or permission-fix commands.

If the connection fails immediately, check for a VPN session conflict

On Android, the usual path is Settings → Network & internet → VPN. Check whether another app has Always-on VPN enabled and whether “Block connections without VPN” is affecting your test. On some systems, this menu is under Connection & sharing. Note your original settings before testing, then restore them afterward to suit your security needs.

To authorize the VPN again, have the client you’re testing initiate the system VPN connection request, then check the app name in the system prompt. Work profiles, device management policies, or employer-managed phones may restrict VPN use; an administrator must address those restrictions. Reinstalling the client usually won’t help.

A disconnect after the screen turns off is not the same as a startup crash

If the app works in the foreground but disconnects after the screen turns off, check its background activity options under Settings → Apps → select the client → Battery. Some manufacturers also have separate auto-start or background protection settings. Loosening restrictions may increase battery use, so first confirm that the app is actually being stopped in the background, then adjust settings as needed.

If the logs show only node connection timeouts or DNS lookup failures while the interface and service are still running, troubleshoot the network and DNS instead. Changing DNS servers won’t fix a YAML parsing error, and switching nodes won’t fix a crash in the app’s native libraries.

iOS app closes on launch: check the app and network extension separately

iOS clients typically use Network Extension to create a VPN tunnel. Their installation process differs from Android APKs, and you shouldn’t assume every iOS client fully supports mihomo configs. If the interface opens but the connection stops immediately, check the client’s connection log. If the app closes as soon as you tap its icon, check the app itself, system compatibility, and installation source first.

• Restart your device and check for an update through the original installation channel. If you installed the app through TestFlight, check whether the test build has expired.
• Go to Settings → General → VPN & Device Management to review existing VPN entries. Don’t delete work- or school-managed profiles without a good reason.
• Go to Settings → Privacy & Security → Analytics & Improvements → Analytics Data, then look for an entry for the app or extension around the time of the issue. Whether a record appears depends on your system and diagnostic settings.

JetsamEvent in Analytics Data may indicate that a process was terminated under memory pressure; it doesn’t confirm a code crash. If the app exits only after loading large rule sets, try reducing the number of rule providers and compare the results. Then share the logs with the client maintainer for review.

On iOS, Offload App usually keeps documents and data, while Delete App removes local data. They serve different purposes: offloading may preserve the faulty state, while deleting the app means you’ll need to export your config first. Don’t delete the app unless you have a way to restore it.

Still crashing? Share reproducible details, not subscription credentials

When reporting the issue, describe the steps in one sentence, for example: “Cold launch opens Settings; after I select a config and tap Connect, the app closes at the same step.” Include your OS, app, and core versions, when it last worked, and whether a minimal config starts successfully. Maintainers need steps they can reproduce—not just a screenshot of your home screen.

Optional on Android: capture a crash log with ADB

If you’re comfortable debugging from a computer, install the Android platform tools on a trusted computer, enable USB debugging, and authorize the connection before running the commands below. Reproduce the crash once, then export the log. Turn off USB debugging afterward. If you’re unfamiliar with ADB, use the app’s built-in log export instead.

adb devices
adb logcat -b crash -d > clash-crash.txt

The crash buffer may not include the full error from a separate proxy core, so keep the client startup log too. Before sharing, remove subscription URLs, tokens, node passwords, server addresses, and personal file paths; include only the relevant error context. Don’t post your full config in a public discussion.