Clash Troubleshooting: From Symptoms to a Restored Connection

1. Clash Is Connected but There Is No Internet Access

First distinguish a stopped client, an inactive proxy, and an unusable configuration

“No internet access” is only what the browser reports; the failure may occur at one of three different points. First, the client core may not be running successfully, so the local proxy port is not listening. Second, the core may be working, but the browser or app may not be sending requests to Clash. Third, traffic may have reached Clash but failed to reach the destination because of a node, rule, or DNS problem. Start by checking the client status or log page. If no new log entries appear at all, application traffic probably is not reaching the client; check the system proxy, browser proxy extensions, and TUN mode. If requests keep appearing in the logs when you open a page but end with timeout, connection refused, or DNS error, continue with the node and resolution path.

To confirm that a local port is listening, find the mixed port in the client settings; the common configuration key is mixed-port. The port does not need to use a particular number—the important thing is that the port shown by the client matches the system proxy, browser extension, or terminal environment variables. On Windows, run netstat in a terminal; on macOS and Linux, use lsof. Output confirms that a process owns the port, but verify that the process is the current client. A leftover process from an older client can occupy the port and prevent the new client from starting.

netstat -ano | findstr LISTENING
lsof -nP -iTCP -sTCP:LISTEN

Compare direct and proxied connections

First disable the system proxy and TUN, then visit a local website that normally opens directly to confirm that the underlying network works. Next enable only the system proxy, revisit the same site, and check the Clash logs. This comparison rules out an unauthenticated Wi-Fi network, a disconnected cable, a faulty gateway, or an ISP outage. If the site fails even with the proxy off, changing Clash settings will not help; repair the system connection first. If direct access works but everything fails with the proxy enabled, focus on the local port, rules, node, or DNS.

You can also test by explicitly specifying the local proxy from the command line, avoiding browser cache and extension interference. Replace the port with the mixed port shown in the client settings. If the command returns a response but the browser does not, the core and node are probably working; investigate browser proxy extensions, HTTPS inspection software, or settings that override the system proxy. If the command also times out, inspect the logs at the same moment and confirm which policy group and node handled the request.

curl -I --proxy http://127.0.0.1:7890 https://example.com
curl -I --socks5-hostname 127.0.0.1:7890 https://example.com

Check rule mode and policy group selection

Rule mode uses domains, IP addresses, and rule sets to decide whether traffic goes DIRECT, through a proxy, or is rejected. After a subscription update, a policy group may revert to its default choice or reference a node that no longer works. Open the proxy or policy group page and trace the active group all the way to its final node; do not stop at the outer group name. To test whether a rule is matching incorrectly, switch briefly to Global mode and select a confirmed working node. If Global mode works but Rule mode fails, the client and node are probably fine; focus on rule sets, policy group references, and rule order. If Global mode also fails, continue checking the node and DNS.

Do not use Global mode indefinitely to hide rule problems. Rules are matched from top to bottom, so a broad rule near the top can intercept a more precise domain rule later. Direct access for all private addresses is usually reasonable, but an incorrect IP range or overly broad domain suffix can bypass the proxy for the destination request. Reviewing the matched rule in the connection record is more effective than repeatedly switching modes. After editing custom rules, reload the configuration and confirm that the client did not fall back to an older configuration because of a YAML syntax error.

Rule out loopback proxy and firewall blocking

Some security software blocks loopback connections. The client may appear to be running while every proxy request sent to 127.0.0.1 fails. Temporarily pause the relevant network-filtering feature for one comparison test instead of deleting firewall rules. Managed devices may also enforce the system proxy through policy; a setting may appear to work and then revert seconds later. Check whether the system proxy page continues to show the local address and port, and make sure two proxy tools are not writing to the system settings at the same time.

If the issue began after waking from sleep, switching Wi-Fi, or disconnecting a VPN, quit the client and confirm that its process has ended before reopening it. When network interfaces change, old connections and DNS caches may remain bound to an interface that is no longer valid. Restarting the client rebuilds the listening port and connection pool more completely than repeatedly clicking the system proxy toggle. If the problem persists, restart the system network interface or the operating system, and keep the pre-restart logs to determine whether the issue recurs.

2. Node Timeouts, Handshake Failures, and Connection Refusals

First determine whether one node or the entire group is failing

A node test showing a timeout does not mean the entire client is broken. In the same policy group, first select at least two nodes from different regions and entry points, then test them against the same address. If only one node fails while others connect, that node may be offline, its entry address may have changed, its port may be unreachable, or its subscription data may be outdated. Switch to a working node and wait for the provider to update the subscription. If every node in one subscription fails but another configuration works, focus on that subscription or service route. Only when every configuration and node times out should you investigate the local network, firewall, system clock, and protocol compatibility.

A client's built-in latency test usually sends an HTTP request to a specified URL. It measures the time needed to complete that test request, not a simple ICMP ping. A test address may be unreachable on the current network, redirect elsewhere, or require a special handshake, causing a usable node to appear to time out. Test real websites and inspect connection logs as well; do not draw conclusions from a single red latency indicator. If the node opens the target site but fails the test, use a stable test address with a small response body, or treat the real access result as the primary signal.

Read common errors by direction

Check the system clock, IPv6, and protocol fields

TLS-based nodes depend on an accurate system clock. If the clock is far off, certificates may be treated as not yet valid or already expired. Enable automatic time synchronization and confirm the time zone is correct; virtual machines, dual-boot systems, and devices that sleep for long periods are especially prone to clock drift. If the logs point to a certificate name or handshake parameter, check that the server name, transport, and port generated by the subscription are complete. When editing a node manually, misspelled fields, incorrect indentation, or the wrong Boolean type can make the core load parameters different from those expected.

IPv6 is another common branch. A node hostname may return both IPv4 and IPv6 addresses while the current network provides only partial IPv6 connectivity. The client then prefers IPv6 and keeps timing out. Test the hostname's IPv4 and IPv6 results on the system, then briefly disable the client's IPv6 option for comparison. If access immediately returns, repair the local IPv6 route, adjust the DNS response policy, or explicitly select a working address family in the configuration instead of marking every node as invalid.

Check the network type and outbound restrictions

Company, school, hotel, and public Wi-Fi networks may restrict uncommon ports or require web authentication first. Disable Clash, open any HTTP page to trigger the captive portal, complete sign-in, and test the node again. A mobile hotspot is a valuable comparison network: if the same device, client, and configuration work on the hotspot but fail on the fixed network, the client configuration is likely correct and the fault lies in the original network's DNS, routing, or access controls. Conversely, if only the same node fails across different networks, a node-side problem is more likely.

Do not hide an unreachable destination by continually increasing the timeout. Timeouts can accommodate high-latency routes, but they cannot fix a wrong address, closed port, or missing route. For longer observation, use one fixed node to access stable sites and record whether failure occurs during connection or transfer. An immediate refusal during connection usually indicates the server port state; a timeout after a long wait points more toward packet loss, a routing black hole, or a filtered entry point; frequent interruption after connection succeeds calls for checking MTU, network transitions, and route quality.

Compatibility issues after a subscription update

If every node becomes invalid immediately after a subscription update but worked before it, first switch back to the most recent working configuration or restore a backup. The subscription may introduce protocol fields unsupported by the current core or change policy group names, leaving rules pointing to groups that no longer exist. Check the configuration load log for messages such as unknown field, unsupported, or proxy group not found. Once client compatibility is confirmed as the cause, choose a maintained client from the downloads page; Clash Plus is a good first option on desktop and mobile. Re-import the original subscription instead of repeatedly overwriting a damaged cached configuration.

3. Subscription Import Failures, Update Failures, or an Empty Configuration

Confirm the complete URL and distinguish a subscription from a webpage

For a failed subscription, first confirm that you copied the complete subscription URL—not the service dashboard home page, a tutorial page, or a redirect link truncated in the browser address bar. Subscription URLs usually include a path and query parameters; chat-app line breaks, QR scanning, browser translation, and text-cleaning tools can remove trailing characters. Paste the URL into a plain-text editor and check that the scheme, domain, path, and query are complete, including the absence of leading or trailing spaces. Never publish the subscription URL in screenshots, shared logs, or public forums; it may contain access parameters that identify your account.

When opened in a browser, a subscription URL may return YAML, encoded content, or a file download. If you see a login page, CAPTCHA, plan details, or an HTML error page, the client cannot parse it as a configuration. A browser download does not guarantee that the client can update, because the browser may be using an existing proxy, login cookies, or different DNS. Conversely, a browser failure does not prove that the URL is invalid; some services require specific request headers. The most reliable evidence is the HTTP status and parse error in the client's update log.

Identify the request stage from the HTTP status

Handle network dependencies during the first import

During a first installation there may be no usable node yet. If the subscription domain cannot be reached directly on the current network, a deadlock results: a proxy is needed to download the configuration, but the configuration is needed to obtain the proxy. Complete the first import on another accessible network, such as a mobile hotspot, or download the configuration on a trusted device and import it locally using a method supported by the client. Return to the original network afterward. Do not hand your subscription content to random online conversion sites; it may contain node credentials and policy information.

If an older configuration is available, select a working node and enable the system proxy before updating the subscription. Some clients offer “update through proxy” or an update-proxy option; confirm that its policy group ultimately selects a working node. If the update still uses a direct connection, find the subscription domain's connection record in the logs and check whether it matched DIRECT or a proxy policy. In Rule mode, incorrectly sending the subscription domain DIRECT is a common reason for update failures. Add a precise domain rule and reload the configuration.

The configuration downloaded successfully but the list is empty

If the update reports success but the node or policy group list is empty, the network request may have completed while the response did not have the structure the client expects. Open configuration management and check the file size and update time; a very small file is often just an error message or empty response. If the client can show the raw configuration, check for top-level fields such as proxies, proxy-groups, and rules. A configuration containing only remote providers may also depend on proxy-providers; in that case, the main file can load successfully while the provider files still need to be downloaded, and a later request failure will leave the node list empty.

mixed-port: 7890
mode: rule
proxies:
  - name: example-node
    type: socks5
    server: 192.0.2.10
    port: 1080
proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - example-node
rules:
  - MATCH,PROXY

The structure above only illustrates how the fields relate; the example address is reserved for documentation. Real configurations should be generated by the subscription service. YAML uses spaces for indentation, not tabs; indentation at the same level must be consistent; names containing colons, hashes, or other special characters should be quoted. When the parser reports a line number, check the preceding line first, because the missing quote or indentation is often there.

Caching, overrides, and duplicate configurations

A client may retain the remote subscription, a local copy, and the configuration currently in use. Updating the subscription does not change the running content if you have not switched to the new configuration; multiple configurations with the same name make this even harder to spot. After updating, confirm that the active item, update time, and configuration source match, then reload once. If configuration management continues to show old content, export necessary custom rules, remove the failed subscription entry, and add it again instead of repeatedly overwriting the same damaged cache.

If the subscription updates successfully but fails again at intervals, record the network in use, system proxy state, and returned status when the failure occurs. Do not click Update repeatedly; the server may rate-limit short-interval requests. Use the provider's recommended automatic update interval. For the import entry point and basic configuration flow, return to the Getting Started guide; the FAQ on the downloads page also covers package and client selection.

4. The Connection Works but Speeds Are Slow, Stuttery, or Unstable

Test the node, route, and local settings separately

Slow speeds are often blamed on the node, but the actual path includes the local device, router, access network, node entry, node exit, and destination site. First disable the proxy and test the underlying network, then enable it with one fixed node and repeat the test using the same site, file, and roughly the same time. Do not base a conclusion on several speed-test sites at once; their server locations, concurrency, and caching differ. If the direct connection is already congested, fix the Wi-Fi signal, router load, or ISP route first. If direct access is stable but the proxy is clearly slower, continue at the node and configuration layers.

When testing nodes, keep the policy group fixed so that url-test does not switch nodes during the test. Compare two nodes in the same region first, then nodes in different regions; this separates single-node load from cross-border routing differences. Latency helps measure interactive responsiveness, not sustained bandwidth. A slightly slower node with little packet loss may provide a steadier web and video experience than a low-latency node with high jitter. For the complete three-layer process, read the node, route, and local-settings troubleshooting checklist.

Observe congestion times and destination differences

If speeds drop only in the evening or on a particular network, route congestion is often responsible. Record normal and abnormal periods instead of permanently changing the configuration after one test. If every destination slows down, prioritize the entry route, node load, and local network. If only one site is slow, consider the route from the node exit to that site, destination-side rate limits, or a mismatched content-delivery region. If pages load normally but large files are slow, check sustained bandwidth, concurrent-connection limits, and the transport protocol rather than only the initial page-load time.

Overly frequent automatic policy-group tests can also cause instability. url-test selects nodes based on test results; when the network jitters, it may repeatedly change the exit, so existing and new connections use different paths and login sessions or long-lived connections can be affected. Use url-test when low latency matters, fallback when availability comes first, and load-balance only when connections need to be distributed. See the policy group configuration guide for how they differ, and do not set the automatic switch interval far below the actual network-change cycle.

Check DNS, IPv6, and connection reuse

A page that is slow on the first visit but faster after refresh often points to DNS lookup or initial connection setup time. Check how long the request remains in the DNS stage of the logs, and test local DNS separately from encrypted DNS. More DNS servers are not automatically better; querying several unstable servers in parallel increases variation, while an incorrect fallback filter may make every query wait through an extra timeout. Keep one stable primary set and a clear fallback policy before evaluating further changes.

When the IPv6 path is poor, a domain's IPv6 result may cause the request to wait for failure before falling back to IPv4, making every new site take several extra seconds. Briefly disabling IPv6 can confirm the direction, but the long-term fix is to repair IPv6 connectivity or align DNS and routing policies. Disabling IPv6 responses only in DNS while other applications continue using IPv6 directly can create new inconsistencies, so validate every change against connection logs.

Troubleshoot TUN, MTU, and LAN devices

TUN mode encapsulates traffic through a virtual interface. With an unsuitable MTU, small requests may work while large responses or uploads repeatedly retransmit. Typical signs include some sites loading while others stall, or text appearing while images and video fail. Within the range supported by the client, lower the TUN interface MTU gradually, changing only a small range at a time and testing the same destination. Do not copy a fixed value from another network environment; broadband, mobile networks, virtual machines, and layered VPNs have different usable MTUs.

If a router provides the proxy on a LAN, confirm that endpoint traffic actually passes through that router and that the gateway and DNS addresses are consistent. If the endpoint uses another DNS server, domain resolution may bypass the intended policy. Dual routers and mesh roaming may also move a device between different exits. When a desktop client has both LAN sharing and local TUN enabled, avoid duplicate forwarding through a router proxy. Double proxying adds handshakes, changes the source address, and spreads diagnostic logs across two devices.

Local resources and background tasks

A laggy client interface does not necessarily mean insufficient proxy throughput. File sync, photo backup, game updates, or a virtual machine can make the CPU, disk, and network compete for resources. Task Manager or Activity Monitor can reveal a background process consuming the network. HTTPS scanning by security software inspects every connection and may add significant latency; use a temporary comparison test to assess its impact, and do not change management policies on a device without the required authorization.

Record five items: “baseline network speed, performance of a fixed node, abnormal time period, destination type, and whether TUN is enabled.” Saying only “it is slow” cannot distinguish latency, bandwidth, packet loss, or DNS time. Once conditions are repeatable, choose a more stable node, adjust the policy group, or fix DNS or MTU. If a node remains unavailable, replacing it is more reliable than stacking complex parameters. If local settings have been modified repeatedly and are difficult to trace, back them up and create a minimal configuration, then restore features one at a time.

5. DNS Resolution Failures, Poisoning, Leaks, and Query Loops

First determine whether the issue is DNS or connectivity

DNS failures are often mistaken for node timeouts. The clearest test is to compare a hostname with an IP address: if the hostname fails but a known IP connects, prioritize the resolution path; if the hostname resolves but the connection still times out, investigate the node, route, and firewall. Use nslookup, dig, or the system's built-in resolver command to inspect returned records, and check the Clash logs to see whether the query was handled by system DNS, Clash DNS, or remote DNS.

nslookup example.com
dig A example.com
dig AAAA example.com
ipconfig /flushdns
sudo dscacheutil -flushcache

Command-line results and browser behavior may differ. A browser may use its own secure DNS, cache, or extensions, while a terminal usually uses the system resolver. Temporarily disable custom browser DNS and check whether all applications use the same path. If only the browser is affected, changing Clash's global DNS is usually not the first choice. If the browser, terminal, and client updates all fail, a system DNS or network-exit problem is more likely.

Understand the difference between redir-host and fake-ip

redir-host returns real resolved addresses, which is straightforward, but rule matching may depend on the result and responses can vary across networks. fake-ip returns a reserved address to the application, while Clash stores the domain mapping and takes over subsequent connections, allowing domain-based routing earlier in the process. Seeing a reserved address in fake-ip mode is usually normal; it is not the real server address. The actual problem is an application bypassing Clash to access the fake IP, or a failed mapping that prevents the connection from being restored correctly.

Some LAN discovery tools, printers, games, and applications that require real IP addresses are not suitable for fake-ip. Use a filter list to return real addresses for specific domains. Start with the exact domain involved instead of adding broad suffixes all at once, which could cause many requests to bypass fake-ip's domain-mapping benefits. After editing, clear the client's DNS cache and the application's cache, then retry the original scenario.

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "localhost"
    - "time.*"
  nameserver:
    - 1.1.1.1
    - 8.8.8.8

The example shows common field relationships; choose actual DNS addresses based on reachability from your network. If a DNS server itself must be accessed through the proxy, ensure a usable bootstrap resolution path still exists during startup. Otherwise, the client must resolve the encrypted DNS hostname before connecting to it, while resolving that hostname depends on a proxy that has not yet been established, creating a circular dependency.

Handle DNS loops and startup dependencies

When a node server uses a hostname, Clash must resolve the node entry before it can establish the proxy. If every nameserver must be reached through that proxy, startup has no available resolver. Provide directly reachable bootstrap resolution for node domains, or use an explicit default-nameserver when supported by the configuration. A bootstrap resolver only needs to help establish the proxy; it does not have to handle every application query. After configuring it, inspect the startup log and confirm that the node entry is resolved before the proxy connection, without repeated timeouts.

TUN mode may also take over all system DNS traffic. If system DNS points to Clash while Clash's upstream incorrectly points back to the system listener, queries can loop locally. The upstream address must not be the client's own DNS listening port, nor should another proxy application forward it back again. When a LAN router, ad blocker, and client all provide DNS, draw the request sequence: application to system, system to Clash, and Clash to upstream. Every hop should have a clear, non-duplicated destination.

DNS leaks and routing consistency

A DNS leak usually means that domain lookups use a different network path from the actual connection. It may not break internet access, but it can return results that do not match the proxy exit region, causing incorrect content delivery, unexpected redirects, or unstable speeds. In Rule mode, domains that require a proxy can use an appropriate remote resolution path while DIRECT domains use local resolution. The key is to keep DNS rules consistent with connection rules. Sending every query to one remote server can also break local services and LAN hostnames.

Do not rely on one webpage when checking for leaks. A page only reflects the resolver used by a particular request, and browser secure DNS, prefetching, and caching can affect the result. A more reliable method is to clear caches, query a new hostname, and observe the Clash DNS log, a system capture, or upstream query records. Confirm that the query followed the expected path before deciding whether there is a privacy or regional-matching issue.

Clear caches and restore a minimal configuration

After changing DNS, clear several layers: the client's own cache, the operating system cache, the browser cache, and any router cache. Usually restart the Clash core first, refresh system DNS next, then fully quit and reopen the browser. Restarting the router repeatedly is not the first step because it also changes the public IP, wireless connection, and DHCP state, adding variables. If access is normal briefly and then fails again, check automatic overrides, DHCP-provided DNS, and browser policies that may be restoring the old settings.

When a complex configuration is hard to diagnose, create a minimal DNS setup: one reachable bootstrap resolver, one enhanced mode, and no extra scripts or overrides, then test ordinary domains. Once stable, add fallback, routing, and filter rules one at a time, recording the behavior after each addition. This is slower than copying a large configuration, but it identifies the field that triggers the issue and prevents differences in network environments from being mistaken for a core defect.

6. The System Proxy Is Enabled but the Browser or Terminal Ignores It

The system proxy only affects applications that honor system settings

The system proxy does not capture all traffic at the operating-system level. Browsers and some desktop applications read the system HTTP, HTTPS, or SOCKS settings, while terminal commands, games, virtual machines, and some cross-platform apps may ignore them completely. “The browser works but the terminal does not” is usually not a Clash failure; the two applications are using different proxy entry points. To cover more traffic, consider TUN mode. For a single command, explicitly setting environment variables is easier to control and undo.

Open the operating system's proxy settings and confirm that the server is the local loopback address and that the port matches Clash's current mixed port. Switching configurations or ports in the client may leave the old system setting unchanged. Also check automatic proxy scripts, enterprise profiles, and other proxy software that may override manual settings. On Windows, different settings pages may ultimately write to the same proxy entries; instead of changing several locations repeatedly, use the client status and the actual system value as the source of truth.

Browser extensions and independent DNS

A proxy extension can override the system proxy. If it is set to direct mode, automatic switching, or an old port, the system proxy toggle will not behave as expected. Test in a private browser window with proxy extensions temporarily disabled, leaving only the system proxy enabled. If that fixes the issue, choose one control method: let Clash manage the system proxy, or point the extension explicitly to Clash's local port. Avoid having two rule sets make decisions at the same time.

A browser's built-in secure DNS may also bypass the system resolution path, making browser DNS behavior inconsistent with Clash settings. It usually does not determine whether the proxied TCP connection can be established, but it can affect rule matching, regional results, and diagnosis. During testing, temporarily use the system default DNS. Once browser and terminal behavior match, decide whether to enable independent browser resolution. For the two troubleshooting paths, see System Proxy Not Working.

Set environment variables for the terminal

Many command-line tools read HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY. These variables apply only to the current terminal session or processes started from it; they persist in new sessions only when written to a shell configuration file. Set them temporarily during troubleshooting and remove them afterward, so commands do not point to a dead port when the client is not running.

export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5h://127.0.0.1:7890

curl -I https://example.com

unset HTTP_PROXY
unset HTTPS_PROXY
unset ALL_PROXY

The h in socks5h means that hostnames are also resolved by the proxy, which helps avoid a mismatch between local DNS and the proxy path. Tools do not all support the same variables or protocols; some recognize only lowercase names, while others use their own configuration files. If curl works but a package manager fails, consult that tool's proxy documentation instead of continuing to change Clash. Windows PowerShell can use environment variables for the current session; they disappear when the window closes, making them suitable for testing.

$env:HTTP_PROXY="http://127.0.0.1:7890"
$env:HTTPS_PROXY="http://127.0.0.1:7890"
curl.exe -I https://example.com
Remove-Item Env:HTTP_PROXY
Remove-Item Env:HTTPS_PROXY

When to switch to TUN mode

TUN mode is more suitable for applications without proxy settings, applications that ignore the system proxy, or traffic that requires UDP interception. TUN creates a virtual network interface and receives traffic through routes, giving it wider coverage than the system proxy but increasing the chance of conflicts with VPNs, virtual machines, containers, and security software. Before enabling it, close other traffic-interception tools and confirm that basic system-proxy mode works. If a problem then appears, you can attribute it to the virtual interface, routes, or permissions rather than the node itself.

After enabling TUN, check whether the system has a new virtual interface, whether the default route is sensible, and whether DNS is being intercepted correctly. Some systems require administrator privileges to create the interface; without them, the UI toggle may turn on while the core log reports device-creation failure. After sleep, network changes, or VPN connections, route priorities may change, causing some traffic to bypass the tunnel or all traffic to stop. Turning TUN off and on can rebuild routes, but recurring problems call for checking conflicting software and interface priorities.

LAN connections and remote devices

To let a phone or another computer use Clash on this machine, enable LAN access and enter the LAN IP of the device running Clash on the remote device—not 127.0.0.1. A loopback address always points to the current device itself. The host firewall must also allow the port from the trusted LAN. First confirm the listening address on the host: if it listens only on loopback, other devices cannot connect. Once it listens on the LAN interface, test port reachability from the remote device.

Restrict LAN sharing to trusted networks, and disable it when sharing is unnecessary on public Wi-Fi. If a remote device can connect to the local port but cannot access the internet, check whether the host Clash log shows requests from that device. No log means the request did not arrive; check the IP, port, client isolation, and firewall. If a log entry exists but the request fails, continue through the node, rule, and DNS branches. Separating the remote-to-host path from the host-to-node path prevents repeated changes on the wrong device.

7. The Client Will Not Start, Keeps Crashing, or Has a Port Conflict

Distinguish the UI from the core

A Clash client usually consists of a graphical interface and a proxy core. Closing the window may leave the core running in the background; conversely, the interface may open normally while the core repeatedly exits because of a configuration error or port conflict. The taskbar, menu bar, and process list can help distinguish the two. When startup fails, end other clients of the same kind and leftover core processes, then start only one client. Do not run multiple programs that write the system proxy, such as Clash Plus, Clash Verge Rev, FlClash, and Clash Nyanpasu, because they can overwrite each other's ports, system proxy, and TUN routes.

Logs are the first source of evidence for locating an exit. If the interface never appears, check the system event viewer, crash reports, or terminal startup output. If the interface appears but the proxy status repeatedly stops, inspect the core log. Configuration parse errors typically identify a field or line number; port conflicts show address already in use; permission problems show permission denied; missing libraries or components are reported as load failures during application startup.

Locate the process occupying the port

The mixed port, control port, and DNS listening port can all conflict. Record the relevant ports in the client settings, then use system commands to identify the owning process. On Windows, match the PID to a process on the Details tab in Task Manager; on macOS and Linux, lsof displays the process name directly. Do not terminate a system process just because it owns the port. First confirm whether it is an old Clash core, another proxy tool, or a required service. If the port belongs to a necessary program, choose a free port in Clash and update the system proxy and terminal variables accordingly.

netstat -ano | findstr :7890
lsof -nP -iTCP:7890 -sTCP:LISTEN
ss -lntp | grep 7890

If the conflict remains after changing the port, the configuration file may be overriding the UI setting, or the client may be loading multiple listener configurations. Check mixed-port, port, socks-port, external-controller, and the DNS listen setting in the active configuration. For detailed process identification and port-change steps, see How to Fix “Port Already in Use” Startup Failures.

Handle corrupted configurations and incompatible fields

If the client crashes immediately after importing a new configuration or the core will not start, switch back to the old configuration first. If the interface cannot open, back up the configuration in the application data directory and move only the most recently added files so the client can start with defaults. Data directories differ by client, so do not bulk-delete files before confirming the path. Prefer the client's reset or safe-start option. When handling files manually, move them while keeping copies, and clean them up only after recovery is confirmed.

Incompatible configurations commonly result from changed core fields, unsupported script syntax, or malformed remote rules. Look for the first error in the log, not the final chain of secondary errors. A single field parse failure can prevent all later policy groups, rules, and DNS settings from being created. Use a minimal configuration to verify that the core runs, then add proxies, policy groups, rules, and DNS in sections. If the minimal configuration is stable, the fault is in the original configuration. If it also exits, check the program files, permissions, and system components.

Permissions, application directories, and system blocking

Installing the TUN service, creating a virtual interface, and writing system proxy settings may require elevated privileges. A normal proxy port usually should not require the client to run permanently as administrator, although installing the service for the first time may trigger an authorization prompt. After authorization is denied, basic system-proxy mode may still work while TUN cannot start. Use the logs to identify the missing permission instead of treating “always run as administrator” as a universal fix.

A non-writable application directory can cause configuration saves, updates, or startup loops to fail. This is especially common when a portable program is placed in a protected or read-only directory, or on a synced drive. Install the client in a normal application directory and ensure that the user data directory is writable. If security software quarantines the core, the UI may repeatedly try to start an executable that no longer exists. Check the system security record and verify the source before restoring it or reinstalling a maintained client from the downloads page.

Post-update failures and clean reinstalls

If crashes begin after an update, restart the system first to rule out an old process or dynamic library still in use. Then back up the subscription URL, custom rules, and override settings, verify the installation source, and reinstall. Reinstalling does not always mean deleting all user data: if the program files are the problem, keeping the configuration may restore your setup; if the configuration or database is corrupted, preserving everything will bring the failure back. A safer approach is to back up first, start the new installation with empty data, confirm stability, and then import settings one by one.

On Windows, check application errors in Event Viewer; on macOS, review system-generated crash reports; on Linux, launching from a terminal often reveals missing libraries and permission details directly. Before sharing logs, remove subscription URLs, node credentials, local usernames, and directory paths, keeping only the relevant error context. If the crash is reproducible, record which page was opened, what type of configuration was imported, whether TUN was enabled, and what the previous action was. This is far more useful than a screenshot taken after the application exits.

Build a stable state you can roll back to

After recovery, do not immediately re-enable every old setting. Run one configuration with one system-proxy entry point and default DNS for a while, then enable TUN, scripts, and custom overrides one at a time. Keep a working copy of the configuration before each change. For client selection, prefer packages that are still maintained and compatible with the current system. Clash Plus is a good first option on desktop and mobile; Linux users can also choose Clash Verge Rev or FlClash. Discontinued software is suitable only for existing environments and should not be the first choice for new system-compatibility issues.

8. Android and iOS Mobile Troubleshooting

Confirm VPN permission and system status

Mobile Clash clients usually intercept traffic through the system VPN interface, so the VPN indicator in the status bar is stronger evidence of authorization than an in-app button. During the first connection, the system displays a VPN request; after it is denied, the client may remain stuck connecting or disconnect immediately. Open the system VPN settings to confirm that the profile exists, and check whether another VPN, ad blocker, or enterprise security app is using the same interface. Most mobile systems allow only one primary VPN connection at a time; two apps cannot simply be layered together.

Android may also have “Always-on VPN” or “Block connections without VPN” enabled. If either setting is bound to another app, Clash cannot create its interface. If it is bound to Clash while the client core is not running, the system may block all network access. Temporarily disable enforcement to test basic connectivity, then restore it as needed once the client is stable. On iOS, deleting the old VPN profile and authorizing again can resolve a mismatch between the saved system profile and the current app state, but first confirm that no organization-managed profile is present.

Background limits, battery optimization, and dropped connections

Mobile operating systems restrict background apps. If the proxy disconnects after the screen has been locked for a few minutes and recovers when the client is reopened, battery optimization, background-activity permissions, or vendor cleanup policies are usually involved. On Android, exempt the client from battery optimization, allow background activity, and retain the necessary permission in the system's auto-start manager. Menu names vary by vendor, but the test is the same: keep the network unchanged, compare the screen-on, locked-screen, and battery-saver states, and note when the VPN indicator or client logs disappear.

iOS manages background network extensions more consistently, but Low Power Mode, network changes, and resource reclamation can still trigger reconnects. If the connection fails every time you switch from Wi-Fi to cellular, wait for the interface transition to finish, then disconnect and reconnect once manually. Repeatedly tapping Connect in a short period can leave several incomplete states. Quit the app, turn off the connection in system VPN settings, and reopen it for a cleaner test.

Wi-Fi, cellular data, and Private DNS

If access fails only on Wi-Fi but works on cellular, the subscription and nodes are probably usable. Check Wi-Fi authentication, router DNS, IPv6, and client isolation. On public Wi-Fi, disconnect the VPN to complete captive-portal authentication, then reconnect Clash. If only cellular data fails, investigate mobile-network IPv6, data-saving settings, the carrier access point, and reachability of the node entry. Try nodes known to work well on that network and briefly compare IPv6-related settings.

Android Private DNS uses system-level encrypted resolution and may create a different path from the client's DNS interception. If hostnames fail while IP addresses work, temporarily set Private DNS to Automatic to test for a conflict. iOS encrypted-DNS profiles, content filters, and browser-specific DNS can have similar effects. Do not change client DNS, system Private DNS, and router DNS at the same time; test one layer first, record the result, and continue from there.

Per-app proxy and bypass lists

Android clients often provide per-app proxying. If one app cannot connect while the browser works, check whether the app is excluded or whether the current mode proxies only selected apps and the app is not selected. Updated apps, cloned apps, and apps in a work profile may have different identifiers and must be selected separately. After changing per-app rules, fully quit and reopen the target app; existing connections do not automatically move to the new path.

System services, LAN devices, and payment apps sometimes need direct access. Add only the specific app to the bypass list based on a confirmed failure instead of bypassing large groups of system components. Even after bypassing an app, requests made through a browser engine or shared service may not follow the app list completely. Check the destination domain and process information in the connection log, then compare it with the rules instead of relying on the app name alone.

Subscription updates and storage permissions

On mobile, copying a subscription URL is more likely to introduce line breaks or be shortened by the browser. Use the client's paste-and-import entry point and inspect both ends of the URL. If QR import fails, switch to text import to distinguish camera-recognition issues from network-request failures. If an update reports success but nodes do not change, confirm that the selected configuration is the subscription you just updated and reload it manually. The subscription timestamp in the interface does not mean that the running core has switched from an older configuration.

Some Android versions use the system picker for file access. For local imports, select the actual YAML file rather than granting only directory access or selecting an online placeholder. If a cloud file has not finished downloading, the client may read empty content. Save it offline in a file manager first, then import it from the client. When exporting logs or backups, note the save location as well; clearing app data deletes internal configurations, so back up the subscription and custom rules before resetting.

Mobile overheating, battery drain, and unexpected data usage

High battery use usually comes from frequent reconnects, unreachable DNS, overly short node-test intervals, or heavy background traffic. Check whether the client is repeatedly logging connection failures and retries, then use system data statistics to identify which app is continuously transferring data. A test interval that is too short makes every node reconnect repeatedly; failed rule-provider and subscription updates can also create retry loops. Restore automatic tasks to reasonable intervals and disable verbose logging when it is not needed to reduce background load.

If data usage is much higher than expected, check the subscription provider's accounting method, node multiplier, and device background tasks. Forwarded data may appear in both the target app's and the VPN app's system statistics, so do not simply add the two figures. Video autoplay, cloud photo sync, and system updates may resume background transfers once the proxy is stable, making it seem that Clash generated the traffic. Compare fixed time windows after disabling background sync for a more meaningful result.

Mobile recovery procedure

Recover in a fixed order: disconnect the VPN and close other traffic-interception apps; confirm that Wi-Fi or cellular data works directly; reopen Clash and select a known-working configuration and node; authorize the VPN; watch the status-bar indicator and connection logs; then restore Private DNS, per-app proxying, and battery-saving settings. If the minimal setup still fails, switch between Wi-Fi and cellular data for a cross-test to quickly determine whether the issue is the device, current network, or subscription node.

If you need to reinstall, choose a platform-matched client from the Android download section or iOS download section; Clash Plus is a good first choice. Save the subscription URL and necessary rules before reinstalling. After installation, import one configuration and confirm basic access before gradually restoring old settings. Mobile problems often combine system permissions, background limits, and network changes, so a simple recovery process is usually more effective than copying every desktop parameter.