Clash Troubleshooting Guide

No Internet Access: Isolate the Fault

First, check whether your direct connection works

Turn off the client's system proxy and TUN, then quit the client and use a browser to visit a site that normally works without a proxy. Public Wi-Fi may require you to sign in through a captive portal. A connected cable or Wi-Fi icon doesn't guarantee internet access. If browsing still fails, check your router, sign-in status, and other devices. Don't keep switching nodes before the underlying network is working; every failed test would have the same root cause.

If direct access still fails after quitting the client, check for a leftover local proxy address in your system settings and make sure no other VPN is controlling the route. Quitting normally doesn't always undo settings changed by another program. Note the original values before removing any manual proxy you no longer use. On managed devices, follow your administrator's policy. Don't reset every network adapter indiscriminately; that could remove static addresses and custom routes needed for work.

Check the local proxy and outbound connection

Restart the client with only one configuration loaded and keep TUN off. Check that the core starts and note the mixed-port value. The command below assumes it listens on localhost port 7890; if the app shows another port, update it. On Windows, use curl.exe in the terminal to avoid environments that interpret the command as a different tool. The test URL provides a consistent comparison, but cannot confirm that every site is reachable.

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

If an explicit proxy request is refused immediately, check the local listener first; don't blame the remote node. Common causes include a core that didn't start, an incorrect port, or another client already using that port. If the local port accepts the connection but the remote response times out, the request has moved to the next stage. Check the connection log for the destination, outbound policy, and handshake errors. These failures occur at different layers and require different fixes.

Isolate routing mode and rules one variable at a time

Once the local listener works, check which rule matched the test request in Rule mode. Global mode can serve as a brief comparison: select the same known-good outbound and keep the test URL unchanged. If Global mode works but Rule mode doesn't, check rule order, proxy group selection, and the direct connection—not the subscription. Global mode can't fix a broken node; switch back to your original mode after testing.

A proxy group displaying a name doesn't mean it has a valid member selected. Check that the group refers to an existing node or provider, especially if a subscription update changed node names. Rules are evaluated from top to bottom: an overly broad direct rule near the top may catch the destination, and the final fallback must point to a real policy. Don't replace the entire ruleset at once. Confirm the matched rule in the connection log, then make the smallest necessary change.

After recovery, test in a browser, a newly opened terminal, and the app that originally failed. If the browser works but other apps don't, check how those apps connect to the proxy. If only domain-name requests fail, go to the DNS section. If the problem still isn't reproducible, note whether it followed sleep, a network change, or use of another network tool. These details are more useful than repeating that the client is on but doesn't work.

Connection Timeouts: Check Transport and Handshake

Separate test failures from real connection failures

A client's latency test usually targets a specific URL and reflects only that test path—not the status of all your traffic. A blocked, redirected, or temporarily unavailable test URL can make a node appear to time out even when ordinary websites work. Conversely, a successful test only shows that a lightweight request completed; it doesn't prove that video, uploads, or long-lived connections are stable. Re-test with the app that actually failed before marking a node unusable.

Compare different nodes on the same network, then test the same node on another trusted network. If just one node fails, check its service status and settings. If all nodes fail on the current network but work on another, suspect network restrictions or routing. Keep the client mode and configuration unchanged during testing so you can tell whether the difference came from the network or the configuration.

Read the log by connection stage

Open the client's log and temporarily increase its verbosity. Make one request, then capture the relevant lines. A parsing error occurs before the server address is resolved; a connection timeout usually occurs while establishing transport; a handshake failure means the connection reached protocol negotiation. Remote closures, authentication failures, and certificate errors also shouldn't all be diagnosed as a slow network. Start with the earliest error; later messages may be consequences of the first failure.

For TLS connections, first check the system date, time zone, and automatic time settings. Then verify that the server name, transport type, path, and other fields match the server. The server address and the name used for certificate validation may differ; don't substitute one for the other by guesswork. Never treat skipping certificate verification as a general fix. It can hide configuration errors and weaken server identity checks.

Check protocol support and test conditions

Some transports rely on UDP, which a network may restrict even when ordinary web traffic works. If so, compare with another transport offered by your service provider rather than changing only the local port. This doesn't mean all UDP apps are unavailable: the node's underlying transport and the proxied app's transport are separate layers. Check support and routing for each one.

Older cores may not recognize newer protocol fields in a subscription. If the log explicitly reports an unsupported type, check which core the client actually uses, then switch to a compatible client or subscription format. On the download page, start with Clash Plus or choose another maintained client for your system. See the comparison of the original Clash, Meta, and mihomo cores for core and field differences. A configuration file extension alone doesn't determine compatibility.

Launching many parallel tests in quick succession can burden your local network and the remote service, creating even more timeouts. Pause automatic tests, hold to one node, let existing connections finish, and then make a small number of requests. If you contact the service provider, share the redacted failure stage, network type, and time of the test—not authentication details. After a fix, test both a lightweight request and a sustained connection to make sure only the test endpoint hasn't recovered.

Subscription Errors: Separate Download from Parsing

Check whether the configuration was actually downloaded

Subscription updates typically fail at one of two stages: the URL returns no content, or the downloaded content can't be read by the client. Check the update message and logs to distinguish DNS failure, connection timeout, access denied, and configuration parsing errors. If the old nodes still appear, that doesn't mean the update succeeded. Many clients retain a usable cached copy, so the interface can keep working even when the remote refresh fails.

Copy the full subscription URL again from your provider's account page. Check for spaces, line breaks, or punctuation added by a chat app. Query parameters may authorize the request, so removing them at random can break the link. Be aware that other apps may read your clipboard; don't submit the URL to an unfamiliar converter just to test it. If the link has been exposed, replace its access token using your provider's account tools.

Access denied doesn't necessarily mean the client is at fault. The subscription may have expired, exceeded a traffic limit, hit a rate limit, or been blocked by server policy. A login page, error message, or web challenge means a page was retrieved successfully—but not a valid configuration. Check the response type and error; don't share the entire response. If requests are temporarily rate-limited, stop retrying and follow the provider's instructions or check your account status.

Verify the configuration type and update method

A full configuration, node list, and ruleset are different types of content. A full configuration can include ports, proxy groups, and rules; a proxy provider usually accepts node data only; a rule provider accepts rules in a specified format. Importing a node list as a full configuration may leave out rules and proxy groups. Using a full configuration as a ruleset URL will cause a structure error. Confirm which type your provider supplies, then choose the matching client feature.

Subscription downloads also need a working network. Some configurations route update requests through the proxy, while the only usable node depends on that same update—a startup dependency loop. You can temporarily use the client's supported direct-update option or switch to another verified outbound, provided the subscription URL allows it. Don't hand an authorized URL to a third party to fetch it for you.

Parsing errors and local overrides

For YAML errors, start by checking indentation, colons, and list markers around the reported location. Indent with spaces, not tabs, and quote strings with special characters correctly. The line number may point to the next place parsing became impossible, so check the preceding line too. Don't delete the reported field just to make the file load; it may contain authentication, transport, or policy information, turning a parsing error into a runtime failure.

mode: rule
log-level: info
rules:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - MATCH,DIRECT

This snippet is only for illustrating list structure and rule syntax; it contains no proxy outbound and can't replace a full subscription. If the existing configuration uses a differently named proxy group, rules must use the exact same name, including spaces and capitalization. If parsing succeeds but a policy is still reported as missing, trace the reference from the rule to the proxy group, node, or provider—especially if a remote update removed an old name.

Back up the current configuration before making changes, then import the new subscription into a separate copy. Confirm that nodes, proxy groups, and rules are intact before switching over; don't delete the old cache and configuration at the same time. If manual updates work but automatic ones fail, check whether scheduled tasks are affected by sleep, background restrictions, or a network that's not ready at startup. See the FAQ for basic concepts. For the setup sequence, return to the configuration guide; this section focuses on troubleshooting and recovery.

Slow Speeds: Separate DNS from Throughput

Pin down which stage is slow

A page that stays blank, slow data transfer after it starts, and playback that pauses repeatedly can point to DNS, connection setup, throughput, or connection stability. Note the time from clicking to the first response, and whether the transfer slows down once it starts. Don't judge by a single latency indicator. Lightweight probes transfer very little data, so a short response doesn't mean large downloads will be faster. Conversely, a longer round-trip time doesn't necessarily limit sustained throughput.

Test the same target on the same device at roughly the same time, with other downloads, cloud sync, and system updates paused. A weak Wi-Fi signal, roaming between access points, or a busy router can slow both direct and proxied traffic. Use a wired connection or move closer to the access point for comparison, but don't change the device, network, destination, and node all at once. With too many variables, even an improvement won't give you a repeatable conclusion.

Confirm the outbound and connection reuse

Check the destination, matched rule, and actual outbound on the connection page. A proxy group called Auto Select doesn't guarantee that a connection is using the expected member; the path to a test URL may also differ from the path to your actual destination. Existing long-lived connections can keep using the old outbound after a policy switch. Browser connection pools and app sessions won't necessarily reconnect immediately. Close the test session or let it end naturally before starting a fresh comparison; don't use an old connection to judge whether the change worked.

Auto Select and failover solve different problems. The former usually picks a member based on test results; the latter focuses on availability. Neither guarantees the best throughput for every destination. Very frequent checks can also trigger excessive probing. If playback keeps stopping, pin a stable outbound first and see how it performs before restoring automatic selection. Frequent switching adds variables to apps that need persistent sessions.

Check destination differences and protocol limits

If only one site is slow, compare other sites using the same node and check whether the destination uses a content delivery network. Different exits may be routed to different cache locations, and an individual origin may throttle traffic. Changing global DNS may not help: resolution might happen on the proxy side, or the connection may still be using an old address. First determine which side resolves the hostname and whether all requests or just one large resource are slow.

Some apps try to use UDP-based transports, which may fail and then fall back if the route is unstable. The client, node, and access network can all affect this path. You can make a limited comparison in the app's official settings, but don't disable a protocol for every device by default. Once service is restored, note what changed and check for any longer-term compatibility impact.

In a TUN setup, consider path MTU or fragmentation only if small requests work but larger responses stall. First rule out Wi-Fi packet loss and remote throttling, then test one supported client setting at a time. Setting an extremely low MTU arbitrarily adds encapsulation and processing overhead and may mask a routing issue. Record the default value and rebuild the connection after each change. If the improvement isn't repeatable, restore the default rather than keeping unexplained settings.

Check local resources and testing limits

Watch CPU, memory, and disk usage during transfers. If the core is using sustained high CPU while other network apps compete for resources, reduce parallel connections, disable unnecessary debug logging, and compare again. A large number of rules alone doesn't explain slow speeds; consider the specific core, rule behavior, and device resources together. Network inspection by security software can also add overhead, but don't leave device protection disabled just to run a speed test.

After finding the cause, keep only changes that help. If the problem is node capacity or a remote site, local configuration can't guarantee a fix; try another available outbound from your provider or wait for the service to recover. If speeds drop only after waking from sleep, check network interface and route recovery instead of adding more performance tweaks. See the TUN mode setup guide for how virtual network adapters take over traffic.

DNS Issues: Trace the Resolution Path

Find out which resolver is handling the request

DNS problems often look like a site that won't load, but not every hostname failure comes from the same resolver. A browser may use its own encrypted DNS, the operating system has its own cache, and the client core may resolve domains on the proxy side. First identify the path used by the failing app, then check the corresponding logs. A successful system lookup only confirms that lookup path works; it doesn't prove the browser or proxy resolved the same address.

Don't use direct access to an arbitrary IP address as your only test. HTTPS usually needs a hostname for certificate verification and server selection, so an IP-based request can fail even when DNS is working perfectly. Cross-check client logs, system lookup results, and requests to the same hostname. If the log already shows a local listener failure or a remote authentication error, clearing the DNS cache again won't help.

Understand Fake-IP and real-IP modes

Fake-IP returns a virtual address to the app; the core uses its mapping to recover the hostname and route the connection. In this mode, seeing a virtual address in a system lookup is expected and doesn't mean the hostname resolved incorrectly. The connection must then pass through the same core. If the lookup goes through the client but the connection bypasses it, the app may try to connect directly to the virtual address. Check that traffic interception is complete before replacing virtual addresses with public ones.

Some local network services, device discovery protocols, and specialized apps don't work well with virtual addresses. You can filter specific hostnames that actually fail, but don't put every domain on the filter list or you'll change the mode's core behavior. Filter syntax and additional modes can vary by core, so check compatibility first. See Fake-IP vs. redir-host for how they work and where each is appropriate.

Check upstream resolvers and bootstrap dependencies

This DNS snippet is for mihomo-compatible configurations; it isn't a complete proxy configuration. It uses public resolvers to illustrate the roles of bootstrap resolution, encrypted queries, and per-domain policies. Choose resolvers based on reachability on your current network and your needs. The snippet doesn't declare a listening address or change the operating system's DNS settings. Apps use these settings only if the client intercepts their requests.

dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "localhost"
  default-nameserver:
    - 1.1.1.1
  nameserver:
    - https://cloudflare-dns.com/dns-query
  nameserver-policy:
    "example.com":
      - https://dns.google/dns-query

When an encrypted resolver is specified by hostname, the core must first resolve that resolver's own address. That bootstrap lookup is a dependency; if it's unreachable, the encrypted queries can't start. A node server specified by hostname also needs a reliable resolution path. Don't make the only way to resolve the node depend on a proxy connection that hasn't been established yet. If you have a dependency loop, check the client's separate settings for resolving node hostnames and proxy-side DNS.

nameserver-policy selects an upstream for specified domains; it isn't a connection routing rule and can't replace an outbound policy. Interpret fallback and its filters according to the core's documentation, rather than assuming they form a list used only when the primary resolver fails. Adding more resolvers can broaden where queries go; it doesn't automatically improve accuracy or privacy. Start with a minimal, reliable set of upstreams, then add only necessary exceptions.

Clear caches and verify in order

After changing the configuration, reload the core and close existing sessions in the test app; clear the system DNS cache if needed. Don't clear the core's mappings while connections still use old virtual addresses, or addresses and hostnames may temporarily become mismatched. Corporate hostnames need internal resolvers. Replacing them with public DNS often won't help and may break services that were working.

Test a public hostname, a local network name, and the app that originally failed. A privacy checker showing a particular DNS provider is just one clue; it doesn't prove where every query went. Cross-check browser settings, system interfaces, and core logs. For more tests, see DNS leak tests and prevention. Don't treat a single result as a complete analysis of the resolution path.

Proxy Not Working: Check What It Captures

Separate the system proxy from TUN

The system proxy provides an entry point for apps that follow system proxy settings; it doesn't automatically capture every program. Some terminal tools, games, and background services use their own network settings and may ignore the system proxy. TUN captures traffic through a virtual network adapter and routes, but is still affected by interfaces, permissions, and exclusion rules. An enabled switch only shows that the client tried to apply the setting—it doesn't prove the request reached the core.

Test the system proxy with TUN disabled first. Open a fresh browser session and check the connection page for a record of the destination. Then compare with an explicit proxy command. If the command works but the browser doesn't, check browser proxy extensions, app-specific proxy settings, and bypass lists. If the command can't connect to the local listener either, return to listener troubleshooting rather than changing app settings.

Check ports, environment variables, and platform settings

mixed-port provides a shared HTTP and SOCKS entry point; the app must use a supported proxy protocol. The control interface in the configuration isn't a proxy port, so entering it in a browser won't forward web requests. A listener bound only to localhost can't be used directly by a phone or another device. Binding to the local network is a separate security decision: consider authentication and firewall rules instead of opening every interface by default just for testing.

Terminal tools often read proxy environment variables, and already-running processes won't pick up new values automatically. The commands below check the current environment; they don't change system settings. Check for both uppercase and lowercase variables, as well as bypass lists; tools may prioritize them differently. After clearing old variables, open a new terminal to test again. Changing settings in another window doesn't update an existing process.

# macOS / Linux: Check proxy variables inherited by the current process
env | grep -i proxy

# Windows PowerShell: Check proxy-related environment variables
Get-ChildItem Env: | Where-Object Name -Match 'proxy'

Test TUN as a separate step

Once the system proxy works reliably, enable TUN and check that the client has installed the required service and received the necessary permissions. Don't run the entire desktop app with elevated privileges indefinitely just to grant access; prefer the client's service mechanism. A virtual adapter appearing doesn't mean its routes are active. Check that the destination connection reaches the core and that the default network interface is identified correctly.

Running multiple VPNs, virtual machine networks, or other TUN tools at once can create overlapping routes. Disable nonessential traffic-capture tools and test a single client first. After sleep or a network change, the old interface and routes may be stale; re-enabling TUN can prompt the client to detect the network again. Don't delete unfamiliar system routes—they may be needed by a work VPN or virtual machine.

If a local network device isn't reachable, check routing for private addresses and bypass rules instead of forcing all traffic to go direct. Printers, network storage, and internal services may each need a different discovery method. If you're making changes remotely, keep a recovery method ready before altering routes so you don't lose access. See the guide to virtual network adapter traffic capture for configuration details.

For the final check, test the app that originally failed—not just a browser. Note whether it uses the system proxy, its own proxy settings, or TUN, and confirm that the system can connect as expected after the client exits. For apps that don't follow the system proxy, use a supported connection method. An ineffective switch doesn't automatically mean the client has crashed. Rules and DNS can only be diagnosed reliably once you know what traffic the client captures.

Client Crashes: Preserve a Recovery Path

Separate a closed interface from a stopped core

A vanished window, a tray icon that remains, and a proxy that suddenly stops can all come from different processes. Some clients run the interface and core separately, so restarting the interface may not stop an old core. A core crash may also appear in the interface simply as a stopped status. Check the client's status page and system processes, then save the latest logs. Don't keep launching more copies; leftover processes can occupy ports and obscure the original crash.

If the system still points to a local proxy after the client exits, but nothing is listening there, no web pages may load. Restore network access using the system proxy section first, then troubleshoot the app. Don't erase the entire data directory before saving your configuration; it may contain local overrides, policy selections, and subscription records. Keep backups somewhere access-controlled, not in a public repository or as an unredacted issue attachment.

Check architecture, permissions, and startup errors

The installer must match your operating system and processor architecture. A completed download doesn't mean the file will run on your system. Handle installer rejection, an invalid executable format, and a crash after launch as separate issues. When choosing another client, start with Clash Plus in the client list and check its system requirements. Clash for Windows and ClashX Meta are discontinued and shouldn't be the default choices for compatibility with newer systems.

If the log reports that an address is already in use, check for another core instance or a different service using the same port. Close a process you can identify as belonging to an old client, or change the local listening port and update app settings to match. Don't terminate an unfamiliar system process. If you see a permission error, check whether the data directory is writable, whether another account created the files, and whether security software quarantined a required component. Don't disable all protection to bypass the problem.

Isolate the issue with a copy of the configuration

Back up first, then start with a new configuration or separate data directory supported by the client. If a clean environment is stable but the core exits immediately with the original configuration, check recently added providers, rulesets, script support, and field compatibility. A configuration can parse successfully even if external resources are unavailable or the core doesn't support every behavior. Restore sections incrementally to identify the trigger.

If the problem began after an update, note whether the interface, core, or both changed. Don't overwrite files in the installation directory with a core from another source; the client may rely on specific startup arguments and interfaces. Use the client's official core management and recovery options first. Reverting to an older environment can help confirm the cause or serve as a temporary fallback, but isn't a reason to permanently ignore a verified compatibility or security update.

If only the interface is blank while the core still forwards traffic, investigate graphics rendering and interface cache next. Check for an official graphics acceleration setting and change one thing at a time. Before clearing interface cache, distinguish it from user data; don't delete entire directories based on a broad path found online. If the app won't launch, get information from system logs or the client log directory rather than asking users to work in a settings page they can't open.

Check resource use and prepare a reproducible report

If memory keeps growing, the client exits during a subscription refresh, or it crashes after running for a long time, record the trigger. Pause unnecessary automatic updates and intensive probes, reduce the number of external resources, and see whether the issue still occurs. Low disk space can also prevent database writes and log creation. Free up space, but check the partition used for the client's data and account quotas—not just total available storage.

After the fix, reload the backup configuration and confirm that policy selections, overrides, and update tasks are still present. Then test a normal exit and restart. If the issue occurs only with a particular configuration, restore it in stages to find the smallest fragment that triggers the problem. If even a minimal setup crashes, continue checking system compatibility, runtime dependencies, and software defects. Reinstallation is one recovery option, not a diagnosis for every crash.

Mobile Troubleshooting: Background Limits and Network Changes

Android: Check VPN permission and background restrictions

Android clients typically use the system VPN interface to receive traffic. The first connection requires explicit permission. An enabled button alone doesn't prove the tunnel is established, so also check system VPN status and client connection records. A work profile, enterprise policy, or another VPN app may be using the same capability. Confirm which service is active; don't let two tools repeatedly compete for control.

Start with Clash Plus from the Android download page, or choose Clash Meta for Android, FlClash, or Surfboard if needed for compatibility. Clients don't all support the same configuration formats and features; a full Clash configuration isn't automatically compatible with every app. Export any configuration you need before switching, and check whether your subscription provider offers a compatible format.

Disconnects when the screen locks that recover when it wakes often involve battery optimization or background execution limits. Check the app's battery policy, background data access, and any manufacturer-specific auto-start setting. Change restrictions only for clients that need to run continuously; don't exempt every app. If Always-on VPN or blocking connections without a VPN is enabled, network blocking when the tunnel stops may be the expected system behavior—not a broken Wi-Fi connection.

iOS: Check the system tunnel and on-demand connection

Install from the Clash Plus App Store link on the download page; the official website is clashplus.io. Follow the system prompts to authorize the VPN configuration when adding it for the first time. The connection icon is only an indication of system status; verify the traffic path with a real request and the client's logs. If another VPN configuration is installed, check which tunnel is active so you don't mistake an old configuration for the current client's status.

The app's settings screen becoming inactive in the background doesn't mean the system tunnel has stopped. Check whether the destination app can connect, the system VPN status, and the client's logs after reopening it. If on-demand rules are enabled, check whether their conditions cover the current Wi-Fi or cellular network. Network name changes and rule matching can affect connection behavior; repeatedly deleting the system configuration isn't a reliable fix.

Test Wi-Fi and cellular separately

Test a connection on a stable Wi-Fi network first, then turn Wi-Fi off and use cellular data with the same node and mode. If only cellular fails, check the app's cellular data permission, carrier restrictions, and whether the node's transport is reachable. If only one Wi-Fi network fails, check its sign-in page and routing restrictions. On public Wi-Fi that requires browser sign-in, VPN capture may interfere with authentication. Disconnect temporarily to sign in, taking the system's blocking policy into account.

After switching networks, existing connections may retain their old address and route; a brief failure doesn't necessarily mean you need to reimport the subscription. Close the destination app's old session and check whether the client has reconnected; if necessary, turn the current tunnel off and on. Toggling airplane mode repeatedly changes the network, address, and session state at once. Use it only as a limited recovery step, not to identify the root cause. Note whether the problem occurred during the switch or persisted afterward.

Check per-app rules and local network access

Android's per-app VPN list is an easy place to miss an app: if it's excluded, the client won't receive its requests no matter how complete the rules are. Check whether the list is an allowlist or a denylist, and whether newly installed apps are included. Apps may also use system services for downloads, which can behave differently from their main process; check the connection log. One browser working doesn't mean other apps use the same route.

If your phone can't reach network storage, a casting device, or a printer, check local network permissions, private address bypass rules, and device discovery. Discovery protocols differ from ordinary web requests, so opening the device's address doesn't guarantee automatic discovery will work. Don't force all private addresses through the proxy permanently, or clear the entire ruleset just to restore casting. First disconnect the tunnel to verify local network access, then restore the necessary bypass rules one at a time.

Finish with three regression tests: use the app with the screen on, check recovery after locking the screen, and switch between Wi-Fi and cellular. Test the app that originally failed each time, then confirm that permissions and settings survive a device restart. If the issue affects only one app, note whether it uses its own DNS, is excluded by per-app rules, or is subject to background restrictions. For general connection concepts, see the FAQ. For first-time setup, follow the quick start guide instead of rebuilding every setting while troubleshooting.