Clash Troubleshooting Guide

01 No internet access: isolate your network from the proxy connection

Turn off System Proxy and TUN in the client, then open a site that normally works without a proxy. TUN routes traffic through a virtual network interface; disabling it narrows the issue to your regular network connection. If direct access fails too, check Wi-Fi, broadband sign-in, campus network authentication, or your router. Switching nodes repeatedly won’t help if your device has no working internet connection to reach the proxy server.

Confirm the core is running, then check its listening port

Open the client log and look for a message confirming that the local proxy port is listening. A working graphical interface doesn’t mean the mihomo core is running; the core parses the config and forwards requests. If the log stops during config loading, start with the first error and check the config path, indentation, and port conflicts. Don’t focus only on the final exit message—it’s often just a consequence of an earlier error. Note the actual listening port; you’ll need it for the tests below.

If you installed mihomo separately, start by testing the config with the command below. It checks whether mihomo can load the config in the specified directory; it doesn’t confirm that remote nodes are reachable. If the test passes, start the core. With a GUI client, restart the core from the app instead of launching a second process manually, which could compete for the same port. The GUI client may also use a different working directory from the default path shown below.

mihomo -d ~/.config/mihomo -t

Test the local proxy directly, without system settings

First, use an explicit proxy command to access the same URL. This tells the test program which local port to use, without relying on the system proxy setting. The example below assumes the mixed port is 7890; use the port shown in your client. In Windows PowerShell, write curl.exe in the command to avoid differences in how terminals interpret the command name. If the test fails, keep the exact error and note when it occurred.

curl --proxy http://127.0.0.1:7890 --connect-timeout 10 --max-time 30 -I https://example.com

Trace the request through the logs

After sending a request, check the connection list right away. Confirm the destination domain, matched rule, and selected egress. Rule mode routes traffic according to rules, while Global mode generally sends requests to the global policy group; in either mode, check which node the group actually selected. You can temporarily switch to Global mode as a comparison. If that fixes the issue, the likely cause is a rule or policy selection—not the entire network. Switch back to your original rule mode after testing.

If only one site fails, test another unrelated site before concluding that all nodes are down. The destination may require a sign-in or reject your current egress IP. If every site fails after you quit the client, check whether the system still has a proxy address pointing to localhost. If the proxy app has exited but the system keeps sending requests to it, the whole device can appear offline. Clear any stale proxy settings before continuing.

02 Connection timeouts: distinguish probe, handshake, and egress failures

First, find out where the timeout occurs. A client’s node test usually sends a request through the node to a probe URL; it isn’t a basic network ping to the server. The probe URL may be unreachable, return an unexpected status, or fail DNS resolution, all of which can make the test time out. Select a node manually, visit the site you actually need, and check the logs before deleting the entire config based on the node list alone.

Compare one node with the rest of the group

Test one node, then another from the same subscription with a different server address. If only the first fails, check the provider’s status, whether the node has expired, and whether connection parameters recently changed. If all nodes fail at once, first rule out local network issues, subscription account problems, incorrect system time, and public DNS issues. Nodes with different names may still point to the same server, so switching names alone may not give you a useful comparison.

Try another network—for example, switch from home Wi-Fi to a mobile hotspot—but keep an eye on mobile data usage. If the same config works on the hotspot but not your original network, look into access restrictions, routing, or DNS on that network. If it fails on both, check the subscription and protocol settings. Don’t change networks, clients, and config all at once: even if things start working, you won’t know what fixed the issue.

Check the connection stage, not just the final error

Check the server address in the log and note the stage where the connection fails. A local resolution error means the server address hasn’t been resolved. A connection refusal usually means the destination port isn’t accepting connections. A connection timeout may point to packet loss along the route or an unreachable service. If the TLS handshake fails, check the protocol, server name, and authentication settings. These clues don’t prove that the provider is at fault, but they help you decide whether to investigate your local config or the remote service.

Check your operating system’s date, time, and time zone, and make sure time sync is enabled. TLS connections validate certificate dates, so an incorrect device clock can cause handshake errors that look like network problems. If the log reports a certificate name mismatch, check that the subscription is complete and that the server name matches the provider’s instructions. Don’t routinely disable certificate verification; it can hide config errors and weaken connection security.

# PowerShell: check the actual address and port provided by your service
# Reserved domain for demonstrating the command structure
Test-NetConnection example.com -Port 443

The port test above only confirms whether a TCP connection to the specified address can be established. It doesn’t verify the proxy protocol or replace a full request. For protocols that mainly use UDP, a TCP test is even less useful as a measure of availability. Servers may restrict probes, and apps may use different routes. Treat the port test as supporting evidence and make your judgment based on proxy requests, core logs, and the provider’s guidance.

Check that the policy group actually changed the egress

After selecting a node, check the connection details to confirm which egress is actually in use. Some policy groups are nested, so selecting an Auto group may still leave the same inner node selected. Existing long-lived connections may also keep using the old egress. Close only the relevant connections and send a new request; don’t clear every connection right away, as that could interrupt downloads, meetings, or other tasks.

As a last step, update the subscription and contact the provider. Include when the issue occurred, your network type, protocol, and the comparisons you’ve already run—but don’t send the full subscription URL. If the update restores only some nodes, keep using the working ones while the provider investigates the rest. If the log reports an unknown protocol or unsupported field, check core compatibility and visit the downloads page for a maintained client instead of blindly lowering security settings.

03 Subscription failures: check download, parsing, and config merging separately

First, identify which step of the subscription process is failing. A subscription URL retrieves nodes or a full config; an import can fail because nothing was downloaded, or because the downloaded content couldn’t be parsed. Check the subscription manager’s update status and the specific message in the core log. Don’t assume every failure means the URL is invalid, and never paste a private URL into a public converter site—it may contain credentials that grant access to your account.

Check the URL and the returned content

Copy the URL again from your provider’s account page. Make sure you haven’t copied a help page, QR code image URL, or text with spaces. Check that a chat app hasn’t truncated the URL or included punctuation at the end. Some URLs contain long query strings, so don’t discard anything after the question mark. If you recently renewed your account or reset the subscription URL, the old one may no longer work; use the current URL shown in your account.

Check what kind of update error you’re getting. Authentication failures or access denied errors usually call for checking account permissions, URL credentials, and provider restrictions. A missing resource may mean the URL path has changed. For timeouts, first check your internet connection and whether the subscription site is reachable. If the response is a sign-in, maintenance, or access verification page, the downloaded content isn’t a usable config—even if the request reports success. Don’t keep retrying when the error clearly points to an access issue.

If the subscription URL is only reachable through a proxy, check whether the client lets you choose a proxy for updates. If you have a working config, enable it before updating. If you have no working nodes, use another legitimate method provided by the service. Don’t change the URL to an unfamiliar domain, or share your entire config directory just to retrieve a subscription.

Check the subscription format and core compatibility

Distinguish a list of nodes from a full config. A full config may include ports, rules, and policy groups; a node list may need to be added through a proxy provider, such as the source defined by proxy-providers. A client’s subscription import option may not accept every share-link format. Check whether your provider offers a format for Clash or mihomo, then use the matching import option. Simply changing the file extension won’t convert the content.

If an error includes a YAML line number, back up the file and check the indentation, colons, and list markers around that line. YAML uses spaces for indentation; don’t mix in tabs. The reported line may also be where the parser noticed a quote left open on the previous line. Avoid making large manual edits to a downloaded config. Try downloading it again first, then check whether it was damaged while copying, saving, or merging.

# Shows only the proxy provider field structure; merge it into a full config.
# Reserved domain for illustrating the structure; not a usable subscription URL.
proxy-providers:
  subscription:
    type: http
    url: "https://example.com/subscription.yaml"
    path: ./providers/subscription.yaml
    interval: 3600

Preserve working configs while investigating overrides and updates

If the original subscription downloads successfully and startup only fails after enabling a local override, focus on the merge process. An override adds local settings to the subscription and can change DNS, rules, and ports. Disable the most recently added override, then regenerate the runtime config. Don’t edit a temporary file generated by the client; the next update may overwrite your changes and make the issue seem to return.

If an update succeeds but new nodes don’t appear, check whether the currently active config is the one you just updated and whether a policy group filters out the new nodes. Updating a config and switching to it are separate actions. Also check that the local file path is writable and there’s enough disk space. Keep the last working config until the new one passes testing. For the basics of importing a subscription, see the subscription import tutorial.

04 Slow speeds: isolate throughput, latency, and site-specific limits

First, describe what’s slow. A long wait before a page opens, low download speed after a download starts, and video that pauses occasionally are three different symptoms. The first may involve DNS or the connection handshake; the second is more likely to reflect low sustained throughput; the third may also depend on the destination’s content delivery. Record results for the same URL, network, and time period, then compare. Don’t treat a node’s response time as its download speed.

Set up a repeatable comparison

Pause cloud sync, system updates, and other high-bandwidth tasks. On the same device, test one resource directly and another through the proxy. If direct access is slow too, check Wi-Fi signal, router load, and your broadband connection first. A connected Wi-Fi icon doesn’t guarantee a stable link; move closer to the router or use Ethernet if available. Try not to move the device while testing, as changes in signal can skew the results.

Download one reasonably sized file from a reputable source at a time, rather than running several speed tests at once. Short, high-concurrency tests compete for bandwidth and may trigger remote limits, so their results may not reflect normal use. When comparing nodes, keep the resource the same and note the actual egress. Test sites may be in different regions or have different capacity, so their results aren’t directly comparable.

Use connection details to find the real bottleneck

Check which rule matched the slow request. A site’s main page may use different domains for images and video. If only the main domain uses the proxy, subresources may take a direct route that doesn’t work. Conversely, sending nearby resources through a remote server adds latency. Find the specific slow or failing domain in the connection list, then add a suitably scoped rule. Avoid broad keyword rules that affect more traffic than necessary.

If only one service is slow, try the same node with an unrelated service, then another node with the original service. If switching nodes helps, the issue may be the egress route or how the destination handles that egress. If the original service is slow through every node, look into the service itself, account limits, and client playback settings. A video site’s buffering indicator isn’t a direct measurement of proxy throughput; consider it alongside the connection list and actual playback.

Adjust protocol and network adapter settings with care

Check whether the client and other VPN or traffic-filtering tools are handling the same connection. Duplicate interception can add overhead or create indirect routes. Exit one tool and test again instead of uninstalling it right away. If performance drops only with TUN enabled, check routes, DNS interception, and security software. If System Proxy works, you can use it temporarily while investigating TUN compatibility separately.

Don’t make changing the MTU your first response to every slow connection. MTU is the maximum packet size for a network transmission. A mismatch along the route can stall some connections, but smaller isn’t always better. Consider a controlled adjustment only if large requests frequently stall on a particular network and work again on another. Back up the original value, change one setting, and retest the same request. Revert it if there’s no improvement.

Finally, check CPU usage, device temperature, and power-saving settings. Encryption, many open connections, and verbose debug logs can tax older devices. Return logging to its normal level, reduce unnecessary background connections, and test again. Don’t stack a batch of supposed speed-boosting options before finding the cause; interactions between settings make issues harder to reproduce. A fix should reliably improve everyday use, not just produce a higher peak in one speed test.

05 DNS issues: separate system, core, and proxy egress resolution

First, understand where DNS resolution happens. DNS translates domain names into network addresses, and the operating system, browser, and mihomo may each make their own queries. A successful system lookup doesn’t mean the proxy core got the same result. A browser using Secure DNS may also bypass the expected resolution path. When you see a domain-related error, identify which program reported it and how that program resolved the name.

Use different routes to identify the failing layer

First, use a system DNS tool to look up a domain you can normally access, then use an explicit HTTP proxy command to visit it. The first test checks system DNS; the second passes the destination domain to the local proxy. Their results may differ. Don’t replace the hostname in the URL with an IP address as your only test. HTTPS also depends on certificate names and site identification, so an IP-based request may fail without proving that your network is down—and isn’t a good end-to-end test for most users.

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

# socks5h means the SOCKS proxy resolves the destination domain
curl --proxy socks5h://127.0.0.1:7890 -I https://example.com

Before comparing results, note the proxy port and operating mode. Local DNS resolution for SOCKS and resolution by the proxy aren’t the same; a suffix in the command can change where the name is resolved. If system lookups fail but proxy requests work, check system DNS first. If system lookups succeed but the core log reports an error, check the core’s DNS settings, whether its upstream resolver is reachable, and whether DNS requests depend on a proxy connection that hasn’t been established yet.

Check config structure and DNS dependencies

Open the runtime config and check whether dns.enable is enabled and what service nameserver points to. This is the upstream list used for regular domain lookups; proxy-server-nameserver can resolve the proxy server’s own hostname. If resolving a node’s hostname requires connecting to that same node first, you may have a circular dependency. Make sure proxy server names have an independent working resolution path before troubleshooting other domains.

# Diagnostic DNS snippet; merge it into an existing full config.
# Choose upstreams based on reachability and your needs on the current network.
dns:
  enable: true
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - https://dns.alidns.com/dns-query
  proxy-server-nameserver:
    - https://dns.alidns.com/dns-query

Understand Fake IP before deciding an address is wrong. In this mode, domains are assigned reserved IP addresses, which the core maps back to their destinations when connections are made. Seeing a reserved address doesn’t mean DNS is broken. Check whether the subsequent connection is being intercepted correctly. If an app receives a virtual address but bypasses the proxy, the connection may fail. Check the interception scope or add an appropriate filter for domains with a verified compatibility issue instead of clearing all DNS settings.

Check caches, IPv6, and browser settings separately

Existing connections and cached results may keep using the old DNS response after you make a change. Close the target app’s relevant connections, clear the DNS cache using the client’s supported method, and try again. Restart the app if needed; don’t reset the entire device’s network settings right away. If the browser has its own Secure DNS setting, temporarily turn it off for comparison. Note the original setting so you can decide which resolution path to keep once the issue is confirmed.

If the issue only occurs on an IPv6-capable network, check address families and routes separately. Having an IPv6 address doesn’t guarantee a working route to it. Likewise, IPv6 support in the proxy doesn’t mean your local network supports it. You can temporarily compare with one address family at a time, but permanently disabling IPv6 across the system isn’t a universal fix. Once things work again, identify whether the cause was the access network, rules, or proxy egress.

When using TUN, also check whether DNS requests are intercepted and whether LAN devices or corporate domains need local resolution. Don’t send all internal domains to a public resolver; they can usually only be resolved by DNS on the relevant network. For a deeper look at config fields and common setups, see mihomo DNS configuration explained. After each change, test both public websites and internal resources.

06 System proxy not working: test each app’s connection path

First, distinguish the system proxy from traffic interception. A system proxy registers an address with the operating system for apps that read that setting; it doesn’t force every connection through the proxy. Terminal tools, games, background services, and some store apps may not use the same setting. An enabled switch only shows that the client tried to update the system setting—it doesn’t prove that every app is using the proxy. Test with an explicit proxy command first to confirm the core itself works.

Check whether the system setting was actually applied

Open your operating system’s network settings and check the proxy server address and port, along with any automatic configuration script. If the client listens on the local loopback address, the system setting should point to that same local address and the port must match the active config. Don’t copy port numbers from another guide. If the setting changes back by itself, check for another proxy tool, device management policy, or security software that may be overwriting it.

Different Windows networking components may use different proxy settings, so it’s not unusual for a browser to work while a background app doesn’t. On macOS, check the active network service: a proxy set for Wi-Fi may not apply to a later Ethernet connection. Linux desktop proxy settings aren’t guaranteed to cover all command-line programs either. Identify the specific app and use a method it supports, rather than changing multiple system layers at once.

Test the browser and terminal separately

In the browser, disable extensions that control proxy settings, then fully quit and reopen the browser before testing. Some extensions override the system setting, and private browsing may not bypass every organization policy or extension permission. Check whether the browser is set to use the system proxy and watch the connection list while making a new request. If the page loads but the core shows no new connection, rule out a cached page instead of relying on what the browser displays.

In the terminal, test with command-line options before setting environment variables. These variables pass config to a process and usually affect only newly started child processes; they don’t update every terminal window that’s already running. The example below sets common variables only for the current shell session. Variable names vary by tool, so check the tool’s own proxy documentation for build tools, package managers, and remote development environments.

# macOS / Linux: affects only this shell and child processes started afterward
export http_proxy=http://127.0.0.1:7890
export https_proxy=http://127.0.0.1:7890
export no_proxy=localhost,127.0.0.1,::1

# Unset these after testing
unset http_proxy https_proxy no_proxy

The https_proxy variable name indicates that it’s for HTTPS requests; its value can still point to a local HTTP proxy. Don’t change the local proxy URL to HTTPS just because the destination uses HTTPS. Check for existing ALL_PROXY, uppercase variables, and tool-specific settings that may still point to a closed port. If you quit the client, remove or update any persistent terminal proxy variables too.

Use TUN only when needed, and check bypass rules

Consider TUN for apps that genuinely don’t support proxy settings. Before enabling it, make sure the client has the necessary permissions, confirm that service mode or the virtual network adapter starts successfully, and check the core log for routing errors. Service mode lets a background service perform privileged operations; repeatedly running the interface as an administrator isn’t a substitute for diagnosis. If internal network access fails after enabling TUN, turn it off to restore connectivity, then check bypass routes and internal DNS.

Finally, check bypass lists. Some apps can bypass the proxy for local addresses, send specified domains direct, or use network isolation; in those cases, not using the proxy is expected. Loopback addresses in containers, virtual machines, and remote development environments refer to those environments, not necessarily the host, so don’t assume they use the host’s local port. If you expose a proxy to other devices, set clear access controls; for ordinary local use, leave LAN access disabled. For more comparisons, see Troubleshoot browsers and terminals separately.

07 Client crashes: preserve logs, rule out conflicts, and roll back config

First, determine whether the GUI or the core is exiting. The interface disappearing, the interface remaining open while connections drop, and a background service repeatedly restarting after boot may each point to a different layer. Note what triggers the issue: opening the app, updating a subscription, or enabling a feature. Don’t delete the entire app data directory right away. You could lose logs, configs, and recovery clues—and may not be able to recover subscription credentials or local rules.

Capture the issue before changing anything, then check whether the config loads

If the interface opens, use the client’s built-in links to its logs and config folder. If it doesn’t, consult the client’s documentation to find its data directory, then copy the config, overrides, and recent logs to a private backup location. Backups may contain sensitive information, so don’t upload them to a public forum. Screenshots should show the error type, file name, and sequence of events, but redact subscription URLs and authentication fields before sharing.

If the issue started immediately after a config change, revert the latest change and test the config. Valid syntax doesn’t guarantee that all resources are accessible; the log may still report a missing rule file, an invalid policy group reference, or insufficient path permissions. Check which working directory relative paths are resolved from—not just whether the file exists somewhere on the device. A GUI client’s generated config may differ from the original subscription, so inspect the file actually passed to the core.

Check for port conflicts and permission issues

If the log says the address is already in use, check whether another client or an old core process is still running. Multiple standard processes can’t listen on the same port at once. The command below shows clues about which process owns a port; it won’t terminate the process. Once you have the process ID, use Task Manager or a system tool to confirm the program name. Don’t copy bulk process-kill commands from the internet, as they may stop unrelated services.

# Windows PowerShell
Get-NetTCPConnection -State Listen -LocalPort 7890 |
  Select-Object LocalAddress, LocalPort, OwningProcess

# macOS
lsof -nP -iTCP:7890 -sTCP:LISTEN

# Linux
ss -ltnp 'sport = :7890'

If the process belongs to an old client, quit it normally and restart the current client. If another essential service is using the port, choose a free port in the client and update the system proxy and terminal variables too. Don’t change just one setting and test immediately; an app still pointing to the old port will get connection refused, making a port conflict look like a different problem. After changing the port, confirm the logs, system settings, and explicit test command all use the same one.

If you see a permissions error, check whether the config directory is read-only, was copied from another account, or whether security software is blocking the core or virtual adapter. Don’t disable all security protections. Read the system notification, confirm the blocked file path and source, then allow only the component you need. Make sure the installer architecture matches your device, especially on macOS and Linux with different processors; a file extension alone doesn’t tell you whether it’s compatible.

Restore only what’s necessary instead of wiping everything

Turn off TUN, disable newly added overrides, and switch back to the last working config. Check whether the interface and core then run reliably. To test whether user data is damaged, create a separate test environment if the client supports it, or temporarily move the relevant config after making a full backup. Don’t permanently delete every file. Once the test works, add the subscription, rules, and advanced settings back one at a time, checking the startup log after each change.

If only one client keeps exiting and the same subscription works in another maintained client, keep the logs and report the issue to the relevant project. Choose a version for your platform from the client downloads page, and don’t enable traffic interception in multiple proxy clients at once. For a more detailed rollback sequence, see Fix a client that crashes on launch. Confirm that startup, subscription updates, and normal shutdown all work before deleting old backups.

08 Mobile-specific issues: check VPN permissions, background limits, and network changes

With the app in the foreground, run a connection test before locking the screen or switching to another app. Mobile operating systems manage background activity, network permissions, and VPN connections. A config that works on desktop doesn’t guarantee the same permissions or lifecycle on a phone. If it works in the foreground but drops in the background, check background restrictions first. If it can’t connect at all, check permissions, subscription, and nodes rather than blaming battery settings for every mobile issue.

Android: check permissions and background activity

When you connect for the first time, allow the VPN connection in the system prompt and check that another app isn’t already using the VPN interface. Here, VPN refers to the system’s traffic routing interface; it doesn’t necessarily mean the app uses any particular proxy protocol. Ad blockers, enterprise access apps, and other network tools may use the same interface, and enabling one can replace another. Pause other traffic interception tools and test the Clash client by itself.

Open the app’s system settings and check battery optimization, background activity, and data permissions. Menu names vary by device, so use the options shown on your system and allow the client to run in the background as needed. Don’t rely on the app card in the recent apps list; its presence doesn’t mean the service is still running. After locking the screen for a while, check the core log to see whether the service stopped or remained active but needs to reconnect.

Check whether per-app proxying is enabled. Some apps may be on a bypass list, or the client may be set to proxy selected apps only. A newly installed app that hasn’t been selected won’t use the proxy. After changing the setting, restart the target app and confirm its requests in the connection list. Android Private DNS can also affect name resolution. If domains fail, temporarily switch to the system default to compare, then restore your preferred setting if needed.

iOS: distinguish tunnel status, network permissions, and resource updates

On iOS, you can install Clash Plus from the iOS download page and allow it to add a VPN configuration when prompted. The VPN indicator only shows that the tunnel is connected; it doesn’t confirm that the node, rules, or destination service are working. Return to the client to check the active subscription, selected egress, and recent logs, then send a new request. If only one app has an issue, also check whether it’s allowed to use cellular data.

If you can’t reach LAN resources, check whether the app has permission to access the local network and whether the config is incorrectly routing internal addresses through the proxy. Permissions and routing rules are separate; adding a direct rule can’t replace system permission. If connections started failing after a large config or rule update, try removing unnecessary rule sets and reducing concurrent tasks, then check the system logs. Don’t delete every subscription just to restore connectivity.

Retest after switching networks, then prepare useful details

When switching from Wi-Fi to cellular, existing connections may no longer work, and the new network may have different IPv6 support, DNS, and access restrictions. Wait for the network to stabilize, reconnect the proxy, close the target app’s old requests, and test again. If the issue only occurs on one Wi-Fi network, check whether you need to sign in through a web page. Temporarily pause the proxy to authenticate, then reconnect so the sign-in page isn’t sent through a remote egress.

Before enabling system options such as Always-on VPN or blocking connections without a VPN, understand how they behave when the tunnel drops. A temporary tunnel failure may cut off internet access on the whole device; that’s expected behavior, not necessarily a Wi-Fi problem. Note your original settings, then temporarily disable the relevant restrictions for comparison. Restore them after testing according to your needs—don’t leave system policies changed without realizing it.

Put together a reproducible report with your device OS, client name, network type, foreground/background differences, whether only one app fails, and the first error with sensitive details removed. Don’t send your full subscription URL, account screenshots, or entire config. For basic concepts, see the FAQ and glossary. To repeat installation and your first connection, return to the setup guide, restore a minimal working setup, then enable advanced features one at a time.