Clash Troubleshooting Guide

No internet: identify the failing layer

First check whether the device has lost internet access entirely or only after enabling Clash. Turn off System Proxy and TUN in the client, make sure the system proxy settings are restored, then try a site that normally works without a proxy. If it still fails, check Wi-Fi, the router, or the network sign-in page; proxy settings can't fix an underlying connection problem. On public Wi-Fi, complete the captive portal sign-in before re-enabling the client so the login block isn't mistaken for a node failure.

Compare direct access with an explicit proxy

Restore direct access, start the client without enabling TUN, and confirm the core is running. Run the two commands below against the same destination: the first explicitly bypasses the proxy, while the second connects to the local proxy port. On Windows, use curl.exe; in some PowerShell environments, curl may resolve to a different command. The example uses port 7890; replace it with the listening port shown in your client settings.

curl --noproxy "*" -I --connect-timeout 10 https://example.com
curl --noproxy "" -x http://127.0.0.1:7890 -I --connect-timeout 10 https://example.com

An HTTP response means the request completed at least some of the connection process; a non-success status code alone doesn't prove the proxy is disconnected. If the second command immediately returns Failed to connect to 127.0.0.1, check the core and port first. If the port accepts connections but the handshake or remote connection fails, check the rule, proxy group, node, and DNS. One test site only checks that particular route, so retest the site that originally failed.

Check connection records to see if the request reached the core

Open Connections or Logs, clear any filters, and reproduce the problem once. If no matching request appears, the app may not be using the system proxy, may be reusing an existing connection, or may not be routed through TUN. If it does appear, check the matched rule, proxy group, and actual exit node. Don't rely on the dashboard status alone: an open client window doesn't mean the core loaded its config successfully. Fix any config parsing errors before investigating node availability.

If the record shows DIRECT for a destination that should use a proxy, the problem is routing—not node speed. Temporarily switch to Global mode and explicitly select a known-good exit node, then establish a new connection for comparison. Global mode only changes routing for traffic that reaches the core; it won't automatically proxy apps that bypass the client. Restore Rule mode after testing so other sites don't keep using the same exit node.

Re-enable features one at a time

If an explicit proxy works but your browser doesn't, enable only the system proxy, restart the browser, and test again. If a specific app still bypasses the proxy, test TUN separately. Don't start multiple proxy clients, network accelerators, and VPNs at once: they can compete for the system proxy, default route, or DNS. When closing other tools, make sure they've also undone their network changes—not just closed their windows.

Retest the original destination and note which setting changed the result. If both direct and proxied connections fail, check the underlying network. If only the proxy fails, continue to the next section. If the explicit proxy works but regular apps don't, see System proxy not working. To review the import and activation process, return to the subscription import steps; repeated reinstalls won't identify the cause.

Node timeout: check the connection path

A “timeout” in a node speed test only means the request didn't finish within the test's time limit; it doesn't prove the service is down. A speed test also depends on the test URL, DNS resolution, protocol handshake, and destination response. Expand the logs and find the full error from the same time. Check whether the failed connection was to the node server, an upstream DNS server, or the test site. The destination in the error matters: a failure to reach the node needs different troubleshooting from a failure by the node to reach its destination.

Narrow it down by the stage where the error occurs

dial tcp indicates an attempt to establish a TCP connection; the text that follows contains the useful clues. connection refused often means the destination port has no service listening or actively rejected the connection. i/o timeout means a stage timed out; check the address and surrounding log entries. For no such host, start with DNS. Don't assume every error means a port conflict: a local port conflict usually appears explicitly in startup logs as a listen failure.

On the same network, test the same destination using a different exit node selected manually. If only one fails, check whether that node's config has expired, its server port has changed, or the service is down. If all exit nodes fail, check whether they share a server hostname, subscription account, or upstream network. Multiple entries may still depend on the same failing component, so node count alone doesn't provide an independent comparison.

Check DNS, port connectivity, and the protocol handshake separately

Resolving the node hostname through the system can show whether the name resolves at all, but the result may differ from the one used by the core. A reachable TCP port only proves that a connection can be opened; it doesn't validate credentials, protocol settings, or subsequent proxy requests. On Windows, use Test-NetConnection with the actual server and port. Don't treat a successful test to local port 7890 as proof that the remote node is working.

If TCP connects but TLS or the protocol handshake fails, check the server name, device clock, and original subscription parameters. If you manually changed server, servername, or another handshake field, restore the values provided by your service. Don't casually replace a hostname with an IP address: certificate validation and server routing may depend on the hostname. Disabling certificate verification can hide an error, weaken security, and still leave the underlying problem unfixed.

Compare networks instead of endlessly increasing the timeout

If possible, compare the original network with a phone hotspot while keeping the client, config, and test destination the same. If the hotspot works but the original network doesn't, investigate router policies, the network's internet route, or UDP restrictions. If websites work but UDP-dependent apps don't, check whether the selected node and protocol support that traffic. Passing a regular TCP speed test doesn't replace testing a UDP-dependent app or prove that every app should work.

Increasing the speed-test wait time slightly can help distinguish a slow response from no connection, but won't fix invalid credentials or an unreachable route. If the test destination itself can't be reached, try a stable URL suited to the intended use and check whether the client tests for an HTTP status or uses another method. For help interpreting full errors, see Clash log error messages explained. When reporting an issue, share redacted logs, the failure stage, and results from comparing networks—not just a screenshot saying “all timed out.”

Subscription error: separate download from parsing

First determine whether the subscription failed to download or downloaded but couldn't be loaded. In the Config page, run one update and check the HTTP status, parsing error, and timestamp in the message. Repeatedly clicking Update rarely provides more information and may trigger server rate limits. Save your working config before making changes. Don't delete it until the new subscription has been verified, and never post the full subscription URL publicly.

For download failures, check the URL, access, and network route

Copy the subscription URL again from your provider's site, making sure it has no leading or trailing spaces, line breaks, smart punctuation, or copied instructions. A subscription URL isn't the account management page, and it may not be the same as the URL currently in your browser's address bar. Links containing account-specific tokens may stop working after a reset. If you generate a new URL, update the saved URL in the client; changing the profile name doesn't change where it downloads from.

For 401 or 403, check your access, whether the URL is still valid, and any provider restrictions. For 404, check the path. For 429, stop retrying and wait as directed by the provider. Server errors can't usually be fixed by editing YAML. A URL working in your browser doesn't rule out a download issue: the browser may have a logged-in session, while the client makes a separate request that can return different content.

Check whether the update request depends on the current proxy. Some clients let you choose direct or proxied updates, but labels and defaults vary. If the old exit node is down and subscription updates are routed through it, updates can get stuck depending on the broken proxy. Try updating over a working direct connection or temporarily select a verified exit node. Don't disable certificate verification or send your subscription URL to an unfamiliar online converter.

For parsing failures, check the actual format and error line

A successful download doesn't mean the content is compatible with your client. The response could be a YAML config, a list of proxy links, a login page, or an error message. For errors such as yaml: unmarshal errors or cannot unmarshal, use the line number to inspect the structure. If the content starts with HTML, fix the subscription URL or access permissions instead of editing the webpage line by line. Renaming Base64 text to .yaml doesn't turn it into a complete config.

# Shows nesting only; no nodes included and not a complete subscription
mode: rule
mixed-port: 7890
rules:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - MATCH,DIRECT

YAML uses spaces for indentation; don't mix in tabs. List items need hyphens, and fields usually need a space after the colon. The reported line may only be where the parser noticed the problem; a missing quote or incorrect indentation may be on the previous line. Strategy group references must match their defined names exactly. If a subscription includes a protocol or field unsupported by your core, ask the provider for a compatible format or use a compatible client. Deleting unknown fields won't necessarily preserve the original config's behavior.

After updating, verify that the config is active and saved

After seeing “Update successful,” make sure the updated config is active, then check that the expected proxy groups appear on the Proxies page. Some clients separate “download subscription,” “refresh providers,” and “reload core” into different actions; cached data may also make the list appear unchanged. The update is only fully verified when a real connection uses an exit node from the new config. The last-updated time shown in the UI isn't enough on its own.

Local edits made directly to a generated subscription file may be overwritten at the next update. For persistent port, DNS, or rule changes, use the client's supported override, merge, or extension feature, and check the merge order first. For help identifying formats, see Subscription imports: YAML and Base64 formats explained. For your first import, follow the Getting Started guide. If switching clients, start by checking platform compatibility on the Clash Plus download page. A different client can't replace a valid subscription or the right permissions.

Slow speeds: check rules and connection paths

Start by describing what “slow” means: a delay before a page begins loading, a low sustained download rate, or video buffering every so often. These can point to DNS, connection handshakes, a congested exit node, or limits imposed by the app. Keep the destination, file, and exit node the same, and test at similar times. Pause cloud sync, system updates, and other bandwidth-heavy tasks. Don't compare results from different sites or assume one fast speed test guarantees a stable long download.

Confirm the exit node, then compare latency and throughput

Find the slow request on the Connections page and check its matched rule, proxy group, and actual node. A site's homepage and downloads may use different hostnames, so proxying the homepage doesn't mean the file uses the same exit node. Existing connections may keep using the old route after you change a strategy. Close the app or just the relevant connection, then start a new request to compare. Constantly switching entire proxy groups makes results hard to compare.

If Rule mode is slow but Global mode works, check whether the destination matched an unsuitable DIRECT rule or related hostnames are using different exit nodes. If both modes are slow, investigate the node and local network. If only one site is slow, consider rate limits for your exit IP, CDN routing, or regional differences. Switching clients usually isn't the first step; try another exit node to reach the same resource and compare the route.

GeoIP updates: fix only rules that depend on GeoIP

GEOIP matches traffic based on the destination IP's region; it doesn't measure connection quality. If logs show a failed geographic database download or load, first check which data mode the config uses and where the client stores its data. Cores may use different database files and loading methods; don't rename a file found online and overwrite the existing one. The update option is usually under Settings, Core, or a geographic data section; labels vary by client.

After updating, check the logs to confirm the download finished and the database reloaded; a download-start message isn't enough. If the update URL is unreachable, fix the download path before retrying through the client's supported update option. Don't guess a replacement source or delete a readable database to force an update. If you use rule providers, refresh the relevant rule sets separately: GeoIP data and remote rule sets are different resources.

After the database updates, make a new request to the slow destination and check whether its rule match changed as expected. IP geolocation data can be outdated or affected by CDN boundaries. For a specific exception, confirm the intended behavior, then add a narrower domain rule before the broader rule it overrides. The example below shows ordering only. Proxy must refer to a proxy group already defined in your config; replace it with the actual group name. Copying it won't create an exit node.

rules:
  - DOMAIN-SUFFIX,github.com,Proxy
  - GEOIP,CN,DIRECT
  - MATCH,Proxy

Check Wi-Fi, UDP, and the transport path

If every exit node is slow on the same device, test over Ethernet or closer to the router, then compare with a phone hotspot. Wireless interference, router load, and saturated upload bandwidth can all make a proxy unstable. If the slowdown occurs only with TUN enabled, turn TUN off and test the same destination through an explicit proxy. If the difference is consistent, check the virtual adapter, route conflicts, and MTU. Don't apply a fixed MTU value without testing; record the original and change one thing at a time so you can revert it.

Some apps prefer QUIC and may keep retrying when UDP is restricted, even while regular TCP browsing works. If the app allows it, temporarily turn off the relevant feature for comparison; don't disable all UDP as a general speed fix. Keep a record of reproducible conditions: network, exit node, rule, destination, and time. For how proxy groups work, see the proxy group glossary. If the delay occurs only during DNS resolution, continue to the next section instead of repeatedly increasing connection timeouts.

DNS issues: check the resolution path

DNS problems may show up as no such host, a domain that won't load, a long wait on first access, or apps losing connectivity after TUN is enabled. First identify whether the failed lookup is for the node hostname, destination site, or DNS upstream. If the node hostname won't resolve, multiple sites may fail. If only one destination fails, the issue may be specific to that domain or its upstream. Don't replace system DNS, core DNS, and browser secure DNS all at once; you'll lose track of which layer actually took effect.

Compare system, browser, and core DNS results

System nslookup reports only the resolver it actually queried; it doesn't guarantee the browser or core uses the same one. The browser may use its own encrypted DNS, while the core may send specific domains to another upstream via nameserver-policy. Record the system DNS settings, then check the client's DNS settings and the final active config. After making a change, confirm that overrides aren't replacing the subscription fields; editing a file alone doesn't mean the running settings changed.

Use a domain that reliably reproduces the problem, then compare system lookups, browser access, and core logs. If system DNS works but proxied requests fail, check the core's upstream and connection path. If the browser works but other apps don't, check whether the browser resolves names independently. The system, browser, and core may each have separate DNS caches; clearing one won't clear them all. Start a new connection after clearing a cache instead of observing an existing one.

Upstream reachability matters more than the number of DNS servers

With encrypted DNS, connecting to the upstream also requires a working network path. If the upstream is specified by hostname, resolving it may require a bootstrap lookup. Keep the roles of default-nameserver (bootstrap resolution) and nameserver (regular lookups) distinct. If a feature routes upstream connections according to rules, check for a dependency loop: resolving the node requires the proxy, but connecting to the proxy first requires resolving the node. Follow the core's documentation to configure an independent lookup path for node hostnames instead of adding more upstreams.

The example below is for temporarily testing basic DNS connectivity; it isn't a universal recommendation and doesn't include TUN routing. It applies only to mihomo configs that support these fields. Back up existing settings before merging and make sure the local listening port is free. Regular UDP DNS may be restricted or intercepted on some networks, so either result is just one piece of evidence—not proof of how encrypted DNS will work.

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: redir-host
  nameserver:
    - 1.1.1.1
    - 8.8.8.8

Test Fake-IP, local hostnames, and DNS interception separately

With Fake-IP enabled, a synthetic address in the DNS response is expected, provided the subsequent connection reaches the same core and its mapping is available. If an app receives a synthetic address but bypasses TUN, the connection may fail. Don't save a synthetic address as a real server IP on another device or use direct access to that IP to judge a site's status. To exclude specific domains for device discovery or LAN services, add only domains confirmed to conflict; excluding everything makes the test meaningless.

Printers, NAS devices, and internal company domains often rely on local resolvers, search suffixes, or multicast. Public DNS won't know these names, so they may stop resolving if you switch to a public upstream. Check for domain-specific DNS policies and make sure TUN routing still allows access to the LAN. Regular DNS interception may not catch an app's built-in encrypted DNS. If an app keeps bypassing the expected resolution path, compare its own settings instead of expanding the interception rules.

After the fix, retest the same domain, network, and app, then restore any temporarily lowered log level or test settings. Stabilize DNS first, then investigate routing or performance; otherwise, a cache hit can look like a fix. For config structure and overrides, see config.yaml explained: ports, dns, and rules. If DNS works but no connection record appears, go to the traffic capture section instead of changing resolvers again.

System proxy not working: check traffic capture

“System proxy enabled” doesn't mean every app on the device uses Clash. A system proxy typically provides HTTP or related proxy settings to apps that support them. Apps that open their own connections, use separate proxy settings, or ignore system settings may still connect directly. First use the explicit proxy test in the opening section to verify the local service, then check how the affected app routes traffic. If the explicit proxy also fails, fix the core and port before toggling the system proxy again.

Check the address and port set in the system proxy

Check the mixed port or HTTP port in the client, then confirm the host and port match in your system's network proxy settings. The host is usually 127.0.0.1, not the node server address. external-controller is a control API, not a browser proxy port; using 9090 as the proxy port will fail. The proxy protocol must also match—HTTP or SOCKS—unless the config uses a mixed port that accepts both.

On Windows, distinguish user proxy settings from the WinHTTP proxy used by some services; a toggle in one screen doesn't necessarily affect the other. On macOS, check the active network service: Wi-Fi and other adapters may have different settings. Linux desktop proxy settings aren't necessarily used by every app. If a proxy address remains set, find out what wrote it and fix it in the corresponding interface. Don't run a global reset command from the internet if it could disrupt your work network.

Check for port conflicts and app overrides separately

If startup logs show address already in use or a bind failure, check which process is using the port. On Windows, use the command below to view listening ports, then identify the process in Task Manager. Don't terminate a process based on its PID alone; it may belong to another service in use. If you change the port, update the client, system proxy, and any manually configured apps, then restart the connection.

netstat -ano | findstr :7890

Terminal apps may read HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY. Browser extensions may also override the system proxy. Restore the app's system proxy setting or temporarily specify a local proxy explicitly, then compare. After changing environment variables, reopen old terminals and running apps; they may retain previous values. Proxy bypass lists also affect results, so check wildcard entries and IP ranges.

Test TUN only when traffic capture is needed

Test TUN separately only if an explicit proxy works and the target app doesn't support system proxy settings. Confirm that the required service or permissions are enabled and that the virtual interface and routes are in place. An enabled toggle with core errors in the logs still means traffic isn't being captured correctly. Other VPNs, virtual machine networks, or container subnets may conflict with TUN routes. Record the original routes and exclusions, then stop conflicting tools one at a time; don't clear the entire routing table.

Allowing LAN connections and using the local system proxy are separate things; local access usually doesn't require allow-lan. Only check the listening address, firewall scope, and trusted network boundaries if other devices need to use this machine's proxy. Those devices should connect to this computer's LAN IP, not their own 127.0.0.1. For port basics, see the port settings guide. If the client doesn't work after startup, check whether the core actually started with the startup FAQ.

Client crash: preserve evidence before recovery

First determine whether the UI exited, froze, or the core stopped. The proxy core may keep running after the window closes; it may also stop while the window remains open. Check the process list, listening ports, and latest logs to narrow it down. If the whole device has network problems, restore the system proxy and TUN settings first so basic connectivity works, then investigate client data. Uninstalling and reinstalling as a first step can erase the conditions and error logs you need to reproduce the problem.

Save the essential evidence from before and after the failure

Record how the client was started and whether the crash occurred during startup, a subscription update, or opening a specific page. Note whether you had just switched configs. Copy the log file with enough surrounding context; the line before the final message may matter more. Redact paths, server hostnames, and request destinations before sharing logs. System event records and crash reports may also contain your user directory, so don't upload the full raw report publicly.

If the client exits every time it loads the same config, back up its data directory and use the software's config-disable or recovery option. If you can open the UI, switch to a known-good config and see whether it still crashes. If you can't, follow the client's documentation for changing the selected config; don't guess and delete unfamiliar files. Custom rule providers, large configs, and corrupt caches may all contribute. Eliminate one category at a time and keep a reversible backup.

Check the installer, core, and system permissions separately

Check your OS and processor architecture on the client download page, and use the installation method for Clash Plus on your platform. If you choose Clash Verge Rev or FlClash, make sure the package matches your system. Don't overwrite one client's program directory with another's files or swap in just one core binary and expect compatibility. The UI and core may use different control APIs and config generation methods; mixing components makes the problem harder to reproduce.

On Windows, check actual block events in security software and whether required background services can start. Only make exceptions for items you've confirmed are trusted and incorrectly flagged; don't permanently disable device protection. On macOS, verify the app's source and review system prompts before granting the required permissions. Not every client uses the same network extension. For related prompts, see macOS permissions and Keychain troubleshooting. Don't run commands that bypass system protections indiscriminately.

On Linux, start the relevant program from a terminal and check for missing dependencies, display environment issues, or permission errors. Desktop apps and service processes may use different environment variables, working directories, and permissions, so if it starts from the terminal but not the application menu, compare their launch environments. For a system service, check the service manager output and confirm the config path and file permissions. Run desktop apps as a regular user when possible, granting elevated permissions only when a specific feature requires them.

Recover in stages instead of wiping everything

Use the client's cleanup option for cache problems, but first distinguish cache from subscriptions, configs, and credentials. If you need to rebuild user data, quit the UI and related background processes, then move the original directory to a backup instead of deleting it permanently. Start with fresh data and import only the config you need; don't restore every old setting. Once stable, restore overrides, rule sets, and startup options one at a time to identify the trigger.

After recovery, repeat the action that triggered the problem—not just opening the window. Update a subscription, reload the config, and establish a real connection. If the problem persists, report the client name, system architecture, reproduction steps, and redacted error, and say whether it occurs with fresh data. Don't speculate about version compatibility or blame a protocol for a one-off exit. If you need help finding config and log screens, see the client interface walkthrough.

Mobile: permissions, background activity, and network changes

On mobile, first identify whether the connection fails immediately, stops when the screen locks, or breaks when switching from Wi-Fi to cellular. These point to VPN permissions, background restrictions, and network reconnection, respectively. Test on one network at a time and close other apps using a VPN connection before starting the client. Most mobile OSes generally allow only one primary VPN connection at a time. Ad blockers, work access apps, and other network tools may compete with the proxy even when their windows appear closed.

Android: check VPN permission, app scope, and background activity

The first time you connect on Android, the system usually asks for VPN permission. If you denied it, reconnect and approve the request; a selected node in the UI doesn't mean the VPN tunnel is active. If Always-on VPN or Block connections without VPN is enabled, confirm it points to the current client. A disabled old client with system restrictions still enabled can leave the whole device offline. Work and personal profiles are separate, and company policies may restrict traffic capture; don't try to override them with regular app settings.

If only some apps bypass the proxy, check per-app proxy settings, bypass lists, and whether the client is set to include or exclude selected apps. An app mistakenly added to an exclusion list can look like a node failure; first check whether it appears in connection logs. Also review the app's own proxy and encrypted DNS settings. Some apps depend on UDP, so a working website doesn't prove that voice, gaming, or real-time traffic will work. Test the app's actual feature.

If the connection drops when the screen locks, check battery optimization, background activity, and auto-start restrictions for the client. Allow the background connection it needs, then monitor the notification and logs. Settings names and locations vary by device manufacturer; search Settings for the relevant options rather than guessing from another phone's instructions. If it still disconnects, note whether the network changed and whether the process was killed or the VPN remained active with no working connection. Those require different fixes.

iOS: check tunnel status and subscription access

On iOS, use the download page to open Clash Plus on the App Store; the official site is clashplus.io. On first use, approve the system VPN configuration, then return to the app to check the active config and proxy selection. The VPN icon only indicates tunnel status; it doesn't prove the subscription is valid or the remote server is reachable. Verify with a real request and the app logs instead of treating the icon as proof that a node is healthy.

If every site fails after connecting, stop the tunnel and verify the original network first. Then check the subscription, DNS, and exit node in that order. If the issue occurs only on one Wi-Fi network, check whether it requires a captive portal sign-in or restricts certain connection types. On managed devices, VPN settings may be controlled by organizational policy; follow your organization's instructions. Don't delete unfamiliar management profiles to test, or assume a work-network issue is simply a client permission problem.

Compare network switches, hotspots, and data usage under the same conditions

After switching from Wi-Fi to cellular, existing connections, DNS caches, and NAT mappings may no longer work. Wait for the network to stabilize, stop and restart the tunnel, then reopen the app to establish a new connection. If the issue reliably occurs after every switch, record whether each network works on its own and which direction you switched. This helps distinguish an unreachable cellular network from a client that didn't rebuild its connections; deleting the entire config isn't necessary.

Your phone using a proxy doesn't mean devices connected to its hotspot will use the same tunnel. Hotspot traffic and the phone's own VPN are handled differently by the OS; test on the connected device instead of relying on a page that works on the phone. Cellular billing is still governed by your carrier plan; a proxy doesn't change its limits. If data usage looks unusual, check per-app usage in system settings, then look for background updates or large downloads. The client's connection log isn't a billing statement.

After fixing the issue, retest in three steps: access the same destination on the current network, check recovery after locking the screen, and establish a new connection after switching networks. Restore any temporary troubleshooting settings. If it still fails, record the network type, tunnel status, time, and redacted logs, then return to the relevant timeout or DNS section. A clear reproduction path is essential before deciding to switch clients; reinstalling won't replace checks for subscription access, background restrictions, and the actual connection route.