Clash FAQ & Connection Troubleshooting

Clash commonly refers to a category of proxy tools that support rule-based routing. mihomo is an actively developed core in this ecosystem, responsible for parsing configs, matching rules, and establishing connections. Client apps provide the interface, subscription management, and system integration. Whether a config field with the same name is supported depends on the core in use and its version. Before troubleshooting, note the client name and core version from the About or core information screen. Don’t assume that steps for another client’s interface will apply.

A client runs a config; it does not provide a working remote proxy service by itself. Subscriptions typically supply nodes, proxy groups, and rules, but you can also set these up in a local YAML file. After importing, select the config you want to use and choose an available outbound in its proxy groups. A config with only rules and empty proxy groups cannot establish a remote proxy connection on its own. Check with the provider about the subscription source, expiration date, and service limits. Installing the client successfully does not mean the service is ready to use.

For everyday use, choose mode: rule to match connections against rules from top to bottom. Global mode sends connections that reach the core through the global policy; direct mode sends them straight out. These modes do not determine how traffic is captured: switching modes may have no effect on an app that isn’t using the system proxy, an explicit proxy, or TUN. When troubleshooting, first confirm that the app’s connections appear in the logs, then compare the results in rule and global mode.

The system proxy provides proxy settings to apps that follow the system configuration, though some apps ignore it. TUN captures traffic through a virtual network interface and routes, and also involves DNS, permissions, and route exclusions. For your initial setup, use the system proxy to verify your subscription and nodes, then enable TUN if your apps need it. There’s no need to enable every traffic-capture method at once. TUN’s coverage also depends on platform restrictions and config, so an enabled switch alone doesn’t prove that traffic is being captured.

A profile is usually a config entry in the client. It may come from a remote subscription or a local YAML file. Refreshing a subscription fetches the provider’s latest content; overrides add local fields, rules, or proxy group changes when the config is loaded. Merge order varies by client, and edits made directly to a subscription-generated file may be lost after an update. Before making lasting changes, back up the config, review the client’s override documentation, and check the final effective config—not just the original text in an editor.

First, confirm on the config or subscription page that the import completed, then set that config as the one currently in use. Check the update result: a webpage, login prompt, or error message is not a usable config. Next, make sure the subscription is still valid and its content is compatible with the current core. If parsing succeeds but no nodes appear, check whether proxy-groups references proxies or proxy-providers. Don’t share your full subscription URL, and hide access credentials in query parameters before sharing screenshots.

Check the indentation, colons, and list hyphens around the line reported in the logs, especially near your latest edits. YAML uses spaces for indentation; don’t use tabs. Align fields at the same level, and quote strings containing special characters when needed. The reported line may be just after the actual error, so check the preceding section too. Restore the last working config, then change one thing at a time. A config that parses may still contain invalid references, so also check that proxy group names and rule targets exist.

Turn off TUN first and confirm that a regular proxy connection works. Then install or repair the service component as directed by the client. On Windows, check the service status and administrator authorization. On macOS, approve the required network permissions when prompted. On Linux, check the elevation method supported by the client and whether /dev/net/tun is available. Requirements vary by client, so don’t broadly loosen system permissions. If it still fails, close other VPN or virtual network adapter tools and try again. Save the original interface creation error from the logs.

Check startup, core launch, and proxy traffic capture separately. Some clients launch their interface only after the user signs in, and the service component, system proxy, or TUN may not start with it. After restarting, confirm that the client process is running, the current config has loaded, and the selected policy is still available. Then check authorization for system startup items. Also consider whether the network was unavailable at startup, preventing the subscription from being fetched. Don’t keep adding startup items to fix the problem; duplicate instances may compete for the same listening port.

Check your processor architecture in the system’s About settings before choosing a download. Common options include x64 and ARM64 on Windows; Apple Silicon and Intel on macOS; and arm64-v8a and armeabi-v7a on Android. On Linux, also check the package format used by your distribution. A mismatched architecture may prevent installation or launch, or require a compatibility layer. Don’t infer the architecture from the device brand alone. Back up your config before updating, and don’t confuse a client installer with a standalone mihomo core file.

Confirm that the current mode is mode: rule and that you edited the config currently in use. rules are matched in order; a broad rule or MATCH near the top can prevent later rules from matching. Check that the rule target exactly matches a proxy group name, then use the connection logs to confirm the actual domain, destination, and matched rule. If a subscription update overwrote your changes, move them to an override location supported by the client. Don’t leave rules in a local backup file that isn’t loaded.

Use select to choose an outbound manually, for example when you need a fixed region or consistent egress. url-test automatically selects based on results from a specified test URL, but a successful test doesn’t guarantee that every service will work. fallback usually selects the first available outbound in the candidate list, making it useful when you have a clear failover priority. First confirm that the candidate nodes work, then adjust supported fields such as url, interval, and tolerance. None of these group types increases a node’s bandwidth.

First, distinguish updates to the whole Profile from updates to proxy-providers. Profile updates are usually managed in the client’s subscription settings; use the unit shown in the interface. Provider updates are controlled by the config’s interval field, which mihomo measures in seconds. health-check.interval controls health checks, not subscription downloads. Set update frequency according to the provider’s limits. If an update fails, refresh manually and check the error rather than retrying at very short intervals, which may trigger rate limiting.

Consider conversion only if the current client doesn’t support the original format and the provider doesn’t offer a suitable subscription format. Prefer a compatible URL from the provider, or use a trusted tool locally. Submitting a URL to an online converter gives that service access to your subscription. Conversion cannot fix an expired subscription, exhausted quota, or server outage. After converting, check that the node types, proxy groups, and rules were preserved. If the URL is exposed, reset it with the provider.

Open the client’s connection list or logs, clear any filters, and make a fresh request from the target app. Check the domain, process, matched rule, and final outbound. Existing long-lived connections may continue using the previous policy, so close and reopen the app if needed. A webpage loading only confirms that this request succeeded; it doesn’t prove that all apps are being captured. An IP-check page shows only the connection used to access it. Once you’ve confirmed the route, turn off detailed logging to avoid keeping unnecessary browsing records.

Check the subscription update logs first, not just the node test results. HTTP 401 or 403 usually indicates an authorization issue, 404 may mean the URL has changed, and 429 means too many requests; check with the provider for the exact meaning. For timeouts, check whether the subscription domain resolves, whether your network is working, and which route the update request takes. If parsing fails, check whether the response is a webpage or an unsupported format. For certificate errors, verify the system time instead of disabling certificate validation.

The subscription server and proxy nodes are separate connection targets, so a successful subscription update doesn’t mean the nodes are available. Compare a different node and test URL, then check your service quota, node settings, and system time. If only one node fails, report the time and error to the provider. If all nodes fail, check the local firewall, other VPNs, and network restrictions. The test URL itself may be unreachable, causing a timeout; consider actual app traffic too, and don’t delete the entire config based on one test.

First, check that the core is running and that the system proxy address and port match mixed-port or the actual HTTP listening port. Then check whether the browser uses its own proxy settings, an extension, or an enterprise policy, and whether the target address is on the proxy bypass list. Fully quit and reopen the browser, then watch the connection logs. If there’s no request in the logs, the issue is likely with traffic capture; if there is, check the matched rule and outbound. Don’t enable allow-lan just to make local connections work.

Some Windows apps isolated with AppContainer can’t access localhost loopback addresses by default, so they may be unable to connect to a proxy listening on 127.0.0.1. First confirm that the app uses a local proxy, then use the client’s loopback exemption tool to authorize only the apps that need it. The tool may require administrator privileges. This restriction doesn’t affect every Windows app, so don’t exempt all programs in bulk. If an authorized app still can’t connect, check its proxy behavior, DNS, and firewall settings instead of adding the same exemption again.

Turn off TUN first to see whether the basic network connection recovers. Then check the logs for DNS timeouts, route conflicts, and interface errors. If the config enables auto-route, make sure it doesn’t conflict with other VPNs, container networks, or local network routes. If dns-hijack is enabled, check that the DNS service is running and its upstream is reachable. For local network issues, check both route exclusions and rules; adding DIRECT alone may not resolve a conflict at the traffic capture layer. Change one setting at a time and keep a recoverable copy of the original config.