Clash Client System Troubleshooting Guide

01 / CONNECTION

No internet access after enabling Clash

First distinguish “the core is not working” from “traffic entered but processing failed”

If no webpage can be opened after starting the client, the most effective first step is not switching nodes but checking whether requests are reaching the Mihomo core. Open the client’s logs, then refresh an ordinary webpage. If no new connections appear, the issue is usually at the system proxy, TUN interception, browser proxy settings, or local-port layer. If requests keep appearing but end in timeouts, connection refusals, or DNS errors, traffic has reached the core; continue with the node, rule, and DNS layers.

Next, temporarily disable the system proxy or quit the client and check whether the device can access the network directly again. If access still fails, the cause is more likely Wi-Fi, Ethernet, the router, a captive portal, or the system network stack. If access returns immediately, the problem is related to client interception. Do not rush to uninstall it; first check the listening port. The common mixed-port accepts both HTTP and SOCKS connections, and the port entered in the system proxy must match the configuration and client settings.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info
ipv6: true

On Windows, run netstat -ano | findstr :7890 in PowerShell or Command Prompt. On macOS and Linux, run lsof -nP -iTCP:7890 -sTCP:LISTEN. A Mihomo process must be listening before the local proxy entry point can be considered established. If nothing is listening, return to the client and check core startup errors. If another program owns the port, terminate the conflicting process or change both the client mixed port and the system proxy port. For a complete method to identify conflicting processes, read How to troubleshoot a port already in use.

Use direct, global, and rule modes to locate the fault

Once the core is running normally, switch to direct mode first. If direct mode works, the local proxy entry point and DNS are basically functional, so the node or rules are more likely at fault. If direct mode also fails, focus on DNS, TUN routing, and the system proxy. Then switch to global mode and select a known-working proxy node. If global mode works but rule mode does not, a request may be routed to an unavailable policy group by an incorrect rule, or ultimately match an unsuitable DIRECT or REJECT policy.

In rule mode, find the matching result for the target domain in the logs. For example, when visiting a code-hosting site, the logs show the matched rule type and the final policy group. Do not stop at the policy-group name; expand it and confirm which node was actually selected. The group may still be set to a failed manual choice, or it may have no usable options because its health-check address is unreachable. After making changes, send a new request; an existing connection does not automatically represent the result of the new configuration.

Handle TUN, LAN, and firewall boundaries

TUN mode uses a virtual network interface to intercept more application traffic. Its coverage is broader than the system proxy, but it is also more sensitive to permissions, routing tables, and security software. If enabling TUN cuts off the network, disable TUN first and test with only the system proxy. If access returns, the node itself is usually not the primary issue. On Windows, check that the client has permission to create a virtual network adapter. On macOS, confirm that the network extension or system service is allowed. On Linux, check the TUN device, routing rules, and process permissions. Re-enable TUN only after fixing these issues, and do not let the system proxy and multiple third-party VPNs manage the default route at the same time.

allow-lan only determines whether other devices on the LAN can connect to this machine’s proxy; it does not affect whether this machine can access the internet through the proxy. To provide access to the LAN, also verify the listening address, inbound firewall rules, and the router’s client-isolation setting. During troubleshooting, keep allow-lan: false to reduce variables. Finally, check the system date and time zone. A large clock skew can make TLS certificate validation fail, causing handshakes to fail across many websites. After completing these checks, restore rule mode, TUN, and LAN sharing one at a time, retesting after each change.

02 / TIMEOUT

Node timeouts, handshake failures, or failed speed tests

A failed speed test does not mean every connection fails

Client node tests usually access a fixed test address and complete DNS, TCP, TLS, or HTTP requests within a time limit. If the test address is restricted by the current network, its response has changed, or the node cannot reach it, the interface may show a timeout even while other websites work. First verify with real traffic: select the node in global mode, open two different sites, and watch the logs. If webpages work but the speed test fails, adjust the health-check URL or interval instead of declaring the node dead.

If real requests also time out, compare several nodes in the same configuration. When only one node fails, common causes include an unreachable remote endpoint, mismatched protocol parameters, a certificate-name mismatch, or an expired node. When all nodes fail at once, suspect local network restrictions, subscription-field parsing problems, an incorrect system clock, or the carrier’s network path. Test on another network, such as switching from home broadband to a mobile hotspot. If the issue disappears, the configuration and client are broadly sound; focus on DNS, IPv6, UDP, or egress restrictions on the original network.

Use the log stage to locate the error

“timeout” is only the final result; the useful clue is where the timeout occurred. A timeout while connecting to the remote IP usually indicates an unreachable TCP path or a blocked entry port. A TLS handshake error calls for checking the server name indication, certificate domain, and system time. “authentication failed” means the credentials do not match the server. If the node connection succeeds but the target website times out, also consider remote DNS, target-site restrictions, and the policy chain. When sharing logs, keep the error type and target domain, but never expose subscription URLs or authentication fields.

In a protocol configuration, the address, port, authentication details, and transport parameters must remain consistent as one set. When editing YAML by hand, an indentation error can place a field at the wrong level; the client may still import it but fail to establish the connection as intended. Compare it with the original subscription instead of mixing TLS, network types, or plugin parameters from different nodes based on guesswork. A node name is only display text; identical-looking names do not mean identical parameters.

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - Auto
      - DIRECT

  - name: Auto
    type: url-test
    proxies:
      - Node-A
      - Node-B
    url: https://www.gstatic.com/generate_204
    interval: 300
    tolerance: 50

url-test automatically selects a candidate based on test results. interval is the number of seconds between checks; a value that is too short creates extra connections, while one that is too long delays status updates. tolerance prevents frequent switching between nodes with similar latency. During troubleshooting, temporarily change the group to manual select and verify nodes one by one to eliminate automatic selection as a variable. If every node shows the same transient failure, also confirm that the test address resolves directly on the current network.

Test TCP, UDP, IPv4, and IPv6 separately

Web browsing mainly relies on TCP, while voice, gaming, some DNS traffic, and HTTP/3 use UDP. A node that opens webpages successfully does not necessarily support UDP forwarding. If webpages work but calls, games, or QUIC fail, temporarily disable QUIC in the application or route the relevant traffic through a node with confirmed UDP support. Conversely, a node that requires UDP may behave unstably rather than go completely offline when the current network restricts UDP.

IPv6 is another common branch. When a domain returns both A and AAAA records, the system or core may try IPv6 first. If the device has an IPv6 address but an incomplete egress route, the connection waits for IPv6 to fail before falling back to IPv4, making the node appear slow. Temporarily set ipv6: false in the Mihomo configuration for comparison. A clear improvement does not mean IPv6 should stay disabled; check the router’s prefix delegation, default route, and DNS responses, then restore it once the IPv6 path is complete.

Finally, check the device clock, firewall, and other network-filtering software. Security software may allow browser traffic while blocking the Mihomo core from connecting to external addresses. Corporate and campus networks may also allow only common ports. Cross-check in a permitted network environment. If a node fails on two devices and two networks while other nodes in the same configuration work, the problem is usually isolated to that node. Update the subscription or contact its provider instead of repeatedly reinstalling the client.

03 / PROFILE

Subscription import, update, or empty-configuration failures

First confirm whether you received configuration data or a webpage

When subscription import fails, do not keep opening the link in a browser. The client needs parseable YAML, compatible subscription text, or configuration content returned by the subscription service. If the URL returns a login page, error page, CAPTCHA, or HTML redirect, a successful HTTP status still cannot be parsed as configuration. Check the update log for the status code, response type, and parse error to quickly distinguish “no content was downloaded” from “the content was downloaded but is incompatible.”

Common download-layer problems include an incomplete link, query parameters truncated by a chat app, an expired subscription, an incorrect device clock, failure to resolve the subscription domain, or a network that cannot reach the address. Without exposing the URL, copy it again from the service page into the client. Do not remove seemingly unnecessary question marks, equals signs, or parameters; they may be part of authentication. If the browser asks you to sign in, return to the service page for a dedicated client subscription URL instead of copying the management-page URL from the address bar.

Distinguish format errors, incompatible fields, and override failures

If the download succeeds but YAML parsing fails, start with the reported line number. YAML uses spaces for hierarchy; tabs, a missing space after a colon, unclosed quotes, and inconsistent list indentation can invalidate the entire configuration. Node names containing colons, hash marks, or other special characters should be quoted. If the error points to custom overrides, disable them temporarily and import the original subscription directly. If the original works, the problem is in the local override rather than the subscription source.

mixed-port: 7890
mode: rule

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - "DIRECT"

rules:
  - DOMAIN-SUFFIX,example.com,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

If the configuration parses but the client shows zero nodes, determine whether the subscription contains rules only, was converted through an incompatible format, or had node fields discarded by a conversion tool. Extension-field support varies between clients. Clash Plus, Clash Verge Rev, FlClash, and other Mihomo graphical clients generally handle common Mihomo configurations, but some older clients cannot recognize newer protocol fields. For YAML, share links, and other configuration formats, see Subscription format conversion. After conversion, carefully verify that the proxy list, policy-group references, and rule targets still exist.

Keep a working configuration when an update fails

A mature troubleshooting approach does not overwrite the only working configuration. Name and preserve the current configuration, then create a new Profile for the updated subscription. If the remote server returns empty content or incompatible rules, you can immediately switch back to the old profile. For the relationship between Profiles, subscription links, and local config.yaml, read How to manage and switch between multiple configurations.

If the subscription reports a successful update but the nodes do not change, the client may still be using another Profile, or the core may not have reloaded after the update. Confirm the active configuration name, update time, and file path, then click “Apply” or “Reload.” If the configuration contains remote rule sets or proxy providers, check whether those child resources updated successfully. A successful main-configuration download does not guarantee that every referenced remote file is reachable. When a remote file fails, the logs usually show its URL type, status code, or parsing error.

When the network is restricted, do not paste subscription content into an unfamiliar online parser. For conversion, prefer a trusted open-source tool or a locally deployed solution. In the converted result, check that policy groups do not reference missing nodes, that the final rule remains MATCH, and that DNS fields match the current core. After fixing the configuration, visit one direct site and one proxied site in rule mode, then test a configuration update. Do not judge the entire setup by the client merely displaying “success.”

04 / PERFORMANCE

Connected but slow or pages keep stalling

Separate throughput, time to first byte, and connection stability

“Slow” can mean three different things: low large-file throughput, a long wait before a webpage opens, or a connection that alternates between fast and slow. Throughput is mainly affected by node bandwidth, line congestion, and protocol overhead. Slow initial responses more often involve DNS, IPv6 fallback, or connection establishment. Fluctuations may come from wireless signal, frequent automatic policy-group switching, packet loss, or changes in mobile-network conditions. Identify which type you are seeing before choosing a test. A single browser speed-test result rarely distinguishes these factors.

To establish a baseline, stop other downloads, cloud sync, and system updates. Use the same device, network, and test target, and record direct and proxied results separately. If direct access is already slow, fix the local network first. If direct access is stable but every node is slow, inspect the path from the device to the node, the client interception method, and the subscription route. If only one node is slow, switch to another node in the same policy group. Keep the mode unchanged during testing; otherwise rules may send different targets through different exits, making comparisons meaningless.

Check whether rules send high-volume traffic through the wrong policy

In rule mode, the page body, images, video, and download URLs may come from different domains. A homepage opening through the proxy does not mean every resource uses the same node. If the logs show a resource domain matching DIRECT, REJECT, or another policy group, the page may appear to load slowly in parts. Use the developer tools network list to find the domain with the longest wait, then verify its rule match in the Mihomo logs. When fixing it, adjust exact-domain and domain-suffix rules first instead of immediately adding an overly broad rule.

Rules are matched from top to bottom, so a broad rule placed first can hide a later precise rule. For example, once a DOMAIN-SUFFIX rule matches a request, a later rule for the full domain is never evaluated. Reload the configuration and create a new connection after editing. Refreshing the page alone may reuse an old browser connection and make the new rule appear ineffective. If necessary, close the relevant tab, wait for the old connection to end, and try again.

Handle DNS, connection reuse, and transport behavior

When a webpage remains on “Connecting” for a long time, slow DNS queries or failed IPv6 attempts are common causes. Use the DNS section of this guide to compare domain resolution, then temporarily disable IPv6 to test for fallback problems. If the logs show repeated queries for the same domain, check whether other software is clearing the DNS cache and whether the browser has enabled its own Secure DNS. When the browser and Mihomo use different resolution paths, their results and traffic-routing decisions may not match.

Some networks provide unreliable UDP, while browsers prefer HTTP/3. Certain sites may load slowly the first time and recover after a refresh. Temporarily disable browser QUIC or force the traffic to fall back to TCP for comparison. If the fallback is stable, investigate whether the cause is the local network, node UDP support, or the remote path rather than relying permanently on one switch. TUN mode adds virtual-adapter processing; on low-performance devices it may affect high-throughput scenarios, so compare it with system-proxy mode under the same conditions.

Reduce interference from local resources and policy switching

Client-interface lag and proxy throughput are different issues, but limited system resources can affect both. Monitor CPU, memory, and disk usage, and make sure multiple Mihomo core instances are not running in parallel. Large rule sets, frequently refreshed rule providers, and overly short health-check intervals add background work. Set the automatic test interval to a reasonable value and temporarily use manual policy groups during troubleshooting to prevent node switching while testing.

For wireless networks, check signal strength, band, and interference together. When far from the router, proxy connections are more sensitive to packet loss and webpages may retransmit repeatedly. Testing over Ethernet or near the access point quickly separates wireless issues from other causes. Mobile hotspots can also be affected by power saving, signal transitions, and carrier conditions. If the same node works on Ethernet but is slow over Wi-Fi, further node-configuration changes are unlikely to help.

Finally, restore features layer by layer. Start with a manual node, system proxy, rule mode, and default DNS to establish a stable baseline. Then restore automatic testing, TUN, custom DNS, and rule overrides one at a time. Run a webpage, file download, and long-lived connection test after each change. This is the only reliable way to confirm that an optimization did not fix one scenario by breaking another.

05 / DNS

DNS resolution failures, poisoning, or Fake-IP issues

First determine whether the error is in system DNS or Mihomo DNS

DNS converts domain names into addresses. With a system proxy, some applications may resolve domains through the operating system before passing the result to the proxy. With TUN and enhanced DNS, more queries usually enter Mihomo. Before troubleshooting, check the logs to see whether the domain appears, whether a DNS error is reported, and which path handled the query. Command-line nslookup and dig test the system-configured resolver by default and may not match Mihomo’s internal result, so read command output together with client logs.

On Windows, run nslookup example.com. On macOS and Linux, run dig example.com A and dig example.com AAAA. If system queries fail but Mihomo proxied requests work, the issue may affect only directly connected applications. If system queries work but Mihomo logs show errors, check nameserver, proxy-server-nameserver, and the outbound path in the configuration. A returned address does not guarantee a successful connection; also confirm that the resolution used for routing matches the actual exit.

dns:
  enable: true
  listen: 0.0.0.0:1053
  ipv6: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - 1.1.1.1
    - 8.8.8.8
  proxy-server-nameserver:
    - 1.1.1.1

The example above is intended to clarify how the fields relate. nameserver handles general queries, while proxy-server-nameserver can resolve proxy-server domains so the node address does not depend on a proxy chain that has not been established. Choose resolvers that are reachable in the actual network environment. If a resolver is reachable only through the proxy while the proxy-server domain itself needs that resolver, the dependency loop can prevent every node from connecting.

Understand the purpose and limits of Fake-IP

Fake-IP mode returns temporary addresses from a reserved range to applications, then Mihomo restores the original domain through its mapping. This lets routing continue to use domain information and helps TUN intercept applications that ignore the system proxy. Addresses in the 198.18.0.0/16 range are normally not poisoning; they are expected in this mode. The real problems occur when an application caches the temporary address, connects directly without Mihomo, or relies on a real address for a LAN service.

If printers, LAN discovery, corporate intranets, or specific applications behave incorrectly with Fake-IP, switch temporarily to another enhanced mode for comparison, then add precise filters for necessary domains. Keep the filter scope as narrow as possible so you retain the benefits of domain-based routing. After changing Fake-IP settings, clear application and system DNS caches and restart the affected connections; reloading rules alone may not remove old mappings.

Handle caches, browser Secure DNS, and leak paths

The system, browser, Mihomo, and upstream resolvers may all cache results. Clear caches layer by layer instead of clearing only one. On Windows, run ipconfig /flushdns. On Linux with systemd-resolved, run resolvectl flush-caches. On macOS, restart the relevant resolution service or reconnect to the network. Browsers often maintain their own host cache and connection pool; closing all browser processes before reopening usually produces cleaner results.

Browser Secure DNS sends encrypted queries directly to the selected resolver and may bypass the path expected by the operating system and Mihomo. During troubleshooting, temporarily use the system resolver, confirm that rules and Fake-IP work, and then decide whether to restore independent browser resolution. If it must remain enabled, ensure this traffic is routed correctly and understand that the browser’s results may differ from the address database used by the core’s rule providers.

If the issue affects only IPv6 domains, check that the device has a usable IPv6 default route, not merely an IPv6 address. Temporarily setting dns.ipv6: false or global ipv6: false can help isolate the cause, but their scopes differ: the former mainly controls DNS responses, while the latter has broader effects. The final configuration should match the network’s actual capabilities. After fixing it, test a direct domain, a proxied domain, a LAN host, and a site with both A and AAAA records so you do not solve only one website.

06 / SYSTEM ROUTING

System proxy is enabled, but some applications ignore it

The system proxy affects only applications that actively read proxy settings

The system proxy is not a global network switch. Browsers and most desktop applications read the system HTTP/HTTPS proxy, but games, command-line programs, virtual machines, some store apps, and software with its own network stack may ignore it. If the browser works but one application does not, the node is usually not the problem; that application’s traffic has not entered Mihomo. Watch the logs while using it. No connection records means you need to address the application proxy, environment variables, loopback restrictions, or TUN. If records appear but requests fail, return to the rules, DNS, and node layers.

The system proxy usually points to the local loopback address and mixed port, such as 127.0.0.1:7890. If the client changes mixed-port, update the system setting as well. Some clients write the system proxy automatically, but an abnormal exit can leave an old port behind. In that case, the interface saying “system proxy off” does not mean the old value was removed from the operating system; check the system network settings directly. A proxy auto-configuration script and a manual proxy should not point to different entry points at the same time.

Check the effective value on each platform

On Windows, check the manual proxy on the Proxy page in Settings. You can also run netsh winhttp show proxy to view the WinHTTP configuration. The system proxy used by browsers and WinHTTP are not identical; some services read only the latter, so judge based on the application type. Microsoft Store and some UWP apps are also affected by loopback restrictions. Use the client’s loopback tool or follow How to handle Windows UWP app loopback restrictions. Fully quit and reopen the target application after making changes.

On macOS, check the HTTP, HTTPS, and SOCKS entries in the proxy settings for the active network service. Wi-Fi, Ethernet, and other network services each have their own configuration, so a proxy written for one may not apply after switching services. Use scutil --proxy to view the current system result. Linux desktop proxy settings apply only to applications that follow the desktop configuration. Command-line tools usually use the HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY environment variables, and different programs may read uppercase and lowercase variants separately.

# Set these for the current terminal session only
export HTTP_PROXY=http://127.0.0.1:7890
export HTTPS_PROXY=http://127.0.0.1:7890
export ALL_PROXY=socks5://127.0.0.1:7890

# Clear them after testing
unset HTTP_PROXY HTTPS_PROXY ALL_PROXY

Command-line settings must match the protocol actually being listened for. Putting an HTTP address in a SOCKS parameter, or the reverse, causes connection refusals or protocol errors. For a basic test with curl -I https://example.com, run it once with explicit proxy parameters and once without them to distinguish an environment-variable issue from a local proxy-entry issue. Clear temporary variables afterward so later terminal tasks do not accidentally keep using the old proxy.

Consider TUN only when the application does not support proxies

TUN is useful for intercepting traffic from applications that do not read system proxy settings, but it depends on the virtual interface, routing, and DNS working together. Stabilize the system-proxy path first so you do not combine two problems. If only LAN access fails after enabling TUN, check that private-address rules use DIRECT. If a virtual machine or container cannot connect, check whether its network uses the host’s default route and whether TUN excludes the relevant interface. When a corporate VPN and TUN run together, both may modify the default route; define which network handles which destinations.

If an application appears in the logs but the rule result is unexpected, check support for process-matching rules. Operating systems differ in how they identify process names, paths, and sandboxed applications, so do not rely on process rules alone. Domain and IP rules are usually easier to reproduce across platforms. If the application uses fixed IPs or its own encrypted DNS, the logs may lack domain information for routing. Handle it using the target address, port, and process rules together.

Finally, check that the local firewall allows the application to access the loopback address and that the proxy is not listening on the wrong interface. For local-only use, loopback listening is safer. Enable LAN access and configure inbound rules only when other devices need to connect. After fixing the issue, test the browser, command line, and application that originally failed separately. All three entry points must work to confirm a complete system-proxy and interception path.

07 / RUNTIME

Client crashes, core startup failures, or repeated exits

First determine whether the graphical interface or the Mihomo core exited

The graphical client and the Mihomo core are separate layers. When the interface freezes or exits, the core process may still be running and the system proxy may continue pointing to it. Conversely, a normal-looking interface does not prove that the core started successfully. After a failure, check Task Manager or Activity Monitor to confirm the interface and core process states, then check whether the local port is listening. If the interface has exited but the port remains open, close the leftover process before restarting so a second instance does not fail because the port is occupied.

Startup logs usually identify the cause directly: configuration parsing failure, port conflict, insufficient file permissions, damaged rule files, TUN creation failure, or an unreadable database. Record the first clear error rather than only the later cascade. For a parsing failure, switch back to the last working Profile. For a port conflict, find the conflicting process. For a permissions error, check whether the configuration and cache directories are writable. Do not delete the entire configuration directory to solve a single file-permission problem.

Build a minimal configuration that starts

When you cannot tell whether the configuration or client is at fault, use a minimal configuration to validate the core. Keep only a listening port, mode, one DIRECT policy, and a final rule. Do not load remote rule sets or enable TUN. If it starts, the program files and basic permissions are generally fine; the problem lies in a field of the original configuration or an external resource. If it still fails, continue with installation, runtime libraries, system permissions, and ports.

mixed-port: 7890
mode: rule
log-level: info

proxies: []

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,DIRECT

This configuration is only for diagnosing local startup and the direct entry point; it does not provide proxy nodes. Do not use it as a daily subscription after verification. When restoring the original configuration, add DNS, proxies, policy groups, rule providers, and TUN one module at a time. If the error returns after adding one part, the scope is narrowed. A YAML error line may only mark where the parser noticed the problem; the actual indentation or quoting error may be several lines earlier, so inspect the surrounding context.

Handle caches, rule files, and the configuration directory

An interrupted rule-database or remote-resource download may leave an incomplete cache that the core cannot read at startup. Use the logs to identify the specific file, then delete only that cache so the client can download it again. Clearing the whole directory also removes Profiles, overrides, and interface settings, increasing recovery work. Exit the client and back up the configuration directory first. If the client supports configuration export, use that feature whenever possible.

If crashes begin after upgrading or switching clients, consider incompatibility between old settings and the new client. Do not copy an entire application-data directory directly between Clash Plus, Clash Verge Rev, FlClash, and other clients. A safer approach is to reinstall a suitable client and import the original subscription or a reviewed YAML file. Choose the operating system on the downloads page; do not treat another platform’s configuration-directory layout as a universal format.

Handle high load, sleep-wake recovery, and unexpected exits

If the client crashes after running for a long time, check whether it coincides with rule updates, network changes, sleep and wake, or a large number of simultaneous connections. Keeping the log level excessively verbose increases disk writes; daily use generally suits info, with higher verbosity only for short diagnostic sessions. After waking from sleep, if the virtual adapter or default route did not recover, disable and re-enable TUN before restarting the entire system.

If the crash can be reproduced reliably, record the steps that trigger it, operating system, client name, interception mode, and error logs. When reporting the issue, provide a minimal reproduction configuration and remove subscription URLs, node credentials, and personal paths. If it cannot be reproduced consistently, first disable custom overrides, remote scripts, and overly frequent health checks to see whether the base configuration is stable. Restoring features one by one to find the trigger is more likely to produce a reusable fix than repeatedly reinstalling everything.

08 / MOBILE

Android and iOS mobile troubleshooting

First address system restrictions on background networking

Mobile proxies usually intercept traffic through the system VPN interface. If the client disconnects in the background, check battery-saving and background-activity restrictions before blaming the node. Android vendors add their own background limits, so allow the client to run in the background, disable battery optimization, and confirm that the VPN indicator remains in the status bar. Some systems also terminate background services when the screen locks, tasks are cleared, or the network changes; add the client to protected apps or the auto-start list.

iOS manages VPN configurations centrally. A brief reconnect after switching between Wi-Fi and cellular data is normal when the network path changes, but persistent failure requires reconnecting from the client and checking that the system VPN configuration still points to the current app. If multiple VPN, DNS, or content-filtering apps are installed, the system may allow only some network extensions to run in a particular order. During troubleshooting, disable other interception tools and keep only one client active.

Test Wi-Fi, cellular data, and LAN separately

If Wi-Fi fails but cellular data works, common causes include router DNS, IPv6 routing, captive-portal authentication, or LAN restrictions. Disable the proxy, complete Wi-Fi portal authentication, and reconnect the client. If only cellular data fails, check mobile-data permission, data-saving mode, and whether the subscription nodes are reachable on that network. On dual-SIM devices, confirm which SIM is providing data; after a network switch, old connections may need to be rebuilt.

If a mobile device cannot reach a printer, TV, or other LAN device, check local-network permission and private-address routing. On iOS, allow the client to access the local network. Android may also require nearby-device or LAN-related permissions. Private addresses should use DIRECT so router admin pages and local services are not sent through a remote proxy. With Fake-IP, if a local domain depends on the router’s resolver, add a precise filter or verify it using the real IP.

Handle app routing, UDP, and notification delays

Android clients often provide per-app proxy or bypass lists. If an application does not use the proxy, confirm that it was not added to the bypass list. If only that application cannot connect, temporarily disable per-app routing so all applications use the same policy for comparison. System apps, work profiles, and cloned apps may use different user spaces, so the normal app list may not cover them. Stop and reconnect the VPN after changing the app scope.

Voice, video calls, and games rely more heavily on UDP. If webpages work but real-time communication fails, check node UDP support, cellular quality, and the matched rule. Mobile networks can differ from Wi-Fi significantly in IPv4, IPv6, and NAT behavior, so the same node may perform differently. Temporarily switch to a node with confirmed UDP support or make the application fall back to TCP for comparison, but do not attribute every timeout to UDP.

Notification delays may also come from the application’s own background policy. A working proxy connection does not mean the target application is allowed to wake in the background. Check notification permission, background data, and battery settings first, then look for the corresponding connection in the Mihomo logs. If logging stops completely after the screen locks, focus on keeping the client alive in the background. If logs continue but notifications do not arrive, inspect the app’s push-service rules and system notification settings.

Import, update, and storage-permission notes

When opening a subscription from a browser or chat app on mobile, the sharing flow may send the link to the wrong application. The safer approach is to use the subscription-import entry point inside the client and confirm that the link is complete. When importing a local file on Android, allow access to the selected file. When importing from the Files app on iOS, wait for the cloud file to finish downloading. If old nodes still appear after an update, check the active Profile and manually reload it.

When mobile storage is low, rule-resource updates and log writes may fail. Confirm that the configuration is backed up before freeing space, and do not delete the client’s data directly. If the app crashes frequently, disable complex overrides and large remote rule sets, then use a minimal configuration to verify that the VPN interface can be established. If you need to choose another app, see the Android client list for Clash Plus, Clash Meta for Android, FlClash, and Surfboard; see the iOS downloads section for Clash Plus.

The final mobile troubleshooting step is to rebuild the connection completely: disconnect the client, disable other VPN or DNS tools, toggle airplane mode once, reconnect to the current network, then start the client and select a manual node. Test the browser, target application, lock-screen recovery, and network switching in order. If the browser always works but one application continues to fail, the issue is narrowed to per-app routing or the application’s own network policy. If all applications fail together after a network change, continue with VPN reconnection, background restrictions, and node reachability on that network.