Clash Meta
Troubleshooting
Find issues by stage of use. Check the core, active configuration, and traffic capture method first, then review subscriptions, rules, and network logs. Select a question to expand the steps.
New to Clash Meta? Start with the Getting Started guide. For a step-by-step process, see the Troubleshooting guide.
Basics
Understand the difference between the core, client, and proxy service, and what each mode does.
What’s the relationship between Clash Meta, the mihomo core, and GUI clients?
Clash Meta was a former name for this core project, which is now maintained as mihomo. The core handles proxy protocols, rule matching, DNS, and connections. GUI clients add subscription management, policy selection, system proxy controls, and log views. Different client names do not necessarily mean they use different cores. To check configuration compatibility, find the core name and version on the About page or in the startup logs, then consult the matching documentation. Updating a client’s interface does not always update its core; some clients require a separate update through core management.
Why do I need a subscription after installing a Clash Meta client?
A client provides connection and traffic-routing features; it is not a proxy service. A usable configuration typically includes proxy server addresses, ports, credentials, and the proxy groups and rules that use them. A subscription is one way to distribute this configuration and should come from your service provider. If you run your own server, you can also write a configuration file yourself. Before importing, check that the subscription format is compatible with Clash or mihomo, and treat the subscription URL like a credential. Never share the full URL in public logs, screenshots, or online converters, especially if its query string contains authentication details.
Which mode should I use: Rule, Global, or Direct?
Rule mode is usually best for everyday traffic routing: mode: rule checks connections against rules from top to bottom and sends them to the matching policy. Global mode sends connections handled by the core through the selected global policy; you still need to choose an available proxy. It does not automatically capture apps whose traffic never reaches the core. Direct mode connects core-handled traffic straight to its destination. As a troubleshooting step, you can briefly switch to Global mode to see whether a rule is causing the issue, then restore your original mode. Mode selection and traffic capture are separate: Global mode does not replace the system proxy or TUN, and does not guarantee that all UDP traffic goes through a proxy.
Can I migrate my configuration now that Clash for Windows is no longer maintained?
Most basic YAML configurations can be migrated, but keep the original subscription, client overrides, and scripts separate. Export the subscription URL and back up local settings, custom rules, and policy group names. Then install a maintained client that supports the mihomo core. Import the original subscription first and verify the basic connection, then restore overrides one at a time. Older clients’ script APIs, configuration directories, and system integrations may not be compatible, so copying the entire program folder is not enough. After migration, disable the old client’s system proxy, background service, and startup entry to prevent two cores from competing for ports or changing routes.
Setup
From importing a subscription to starting the core, check the response, listening port, and system permissions first.
What should I check first if a subscription won’t import or stops working after an update?
Manually update the configuration or subscription and check the response status and error details. A 401 or 403 usually indicates an authentication, permission, or access policy issue; for a 404, verify the URL; for a timeout, first check whether the subscription domain is reachable. If the download succeeds but parsing fails, check whether the response is actually a login page, an error page, or a format other than a Clash configuration. Keep a working copy before updating, and avoid repeatedly deleting and re-creating the subscription. Also check whether the client is configured to fetch subscriptions through the current proxy. If that proxy is unavailable, try updating directly if your network allows it, then ask your provider to confirm that the subscription is still valid.
What does mixed-port: 7890 mean, and how do I fix a port conflict?
mixed-port is a listener that accepts both HTTP and SOCKS proxy connections. Port 7890 is common, but not required. When configuring an app’s proxy manually, use the address and port the client is actually listening on; on the same device, this is usually 127.0.0.1. If startup logs show address already in use, quit other proxy clients and any leftover core processes, then check which process is using the port. You can switch to a free port, but update the system proxy, browser extensions, and command-line environment variables too. Some clients override the port in the subscription, so use the final value shown in the settings and startup logs.
TUN mode reports insufficient permissions. How can I check whether the service is running correctly?
TUN creates a virtual network interface and changes routes, so it usually requires administrator privileges or a privileged service provided by the client. On Windows, check that service mode is installed and running, then grant any permissions the client requests. On macOS, install the helper and approve it in system settings. On Linux, check that the service account has the required network permissions. Don’t assume traffic is being captured just because the TUN switch is on; check the logs for interface creation and route setup. If the device is reported as busy, stop other VPN or virtual network adapter services first. Once permissions are restored, restart the core and try again. Don’t work around the issue by disabling the firewall or exposing the control interface more broadly.
How can I find YAML indentation errors after editing config.yaml?
Keep a copy of the file that produced the error, then check the line number in the logs and the surrounding lines. YAML indentation uses spaces, not tabs. Align keys at the same level, prefix list items with hyphens, and leave a space between a key’s colon and its value. The reported line often marks where the parser got stuck, but the actual error may be on the previous line. If the core executable is available, test the configuration with mihomo -t -f config.yaml, pointing to the actual file. Also confirm that all policy groups and rules reference names that exist. With subscription-managed clients, make changes through the override interface; direct edits to a downloaded cache may be overwritten at the next update.
Tips
Manage custom rules, startup behavior, multi-device sync, and DNS routing.
Where do I add custom Clash rules, and why aren’t they taking effect?
In Rule mode, rules are matched in rules order. Put custom rules before broader rules that might match first, and never after the final MATCH rule. For example, DOMAIN-SUFFIX,github.com,PROXY requires a policy or proxy group named PROXY; names are case-sensitive. Use the client’s rule override or prepend-rules option to avoid having subscription updates overwrite your changes. Save and reload the configuration, then check the connection details to see which rule and policy chain were actually matched. Existing long-lived connections may keep using the old route, so close the connection and retry before testing. Domain rules also cannot match requests that use a hard-coded IP address.
Clash starts with Windows, but I still can’t connect. Which settings should I check?
Starting the client at boot, starting the core, enabling the system proxy, and enabling TUN are separate settings. Restart the system and check whether the client is running in the background, the current configuration has loaded, and the core is listening on its port. Then check whether the system proxy or TUN has been restored. In service mode, verify the system service’s startup type and status so the interface doesn’t start before the privileged service is ready. If the network is not connected when you sign in, subscription updates and connection tests may fail temporarily; wait for the network to come up and try again. Don’t enable startup for multiple clients at once. When switching clients, remove proxy and service settings left behind by the old one.
Can I use the same subscription and configuration on my computer and phone?
You can use the same subscription source, but first check the service’s device limit and simultaneous connection policy. Proxy lists and rules are often reusable, while TUN settings, DNS listen addresses, interface names, file paths, and external controller settings may need device-specific overrides. Keep shared settings in subscription management and configure ports and system integration in each device’s client. Don’t share subscription URLs containing credentials or commit controller access credentials to a public repository. After switching devices, check whether your policy group selection was restored. Even with the same configuration file, differences in the operating system’s network stack, VPN permissions, and background policies can affect how it behaves.
How do I check for a Clash DNS leak? Does fake-ip capture all DNS traffic?
fake-ip maps domains to virtual IP addresses to preserve domain information; it does not automatically send every DNS request through the core. First confirm that dns.enable is on, then check system DNS, TUN DNS hijacking rules, and whether the browser or app has encrypted DNS enabled separately. Use the core logs and system network settings to trace DNS requests; the resolver location shown by an online test is only a clue. After changing DNS settings, clear system and browser caches and reconnect. Don’t add multiple nameserver entries at random because test results differ from expectations. First determine which requests are resolved by the system and which go through the core, and how upstream DNS connections are routed.
Troubleshooting
Compare results based on the symptoms, change one setting at a time, and keep a recoverable copy of your configuration.
A proxy node test times out. Is the server down or is my configuration wrong?
A test timeout only means that the specified request did not complete within the allotted time; it does not by itself prove that the server is down. Check that your system clock is correct and the subscription is up to date, then look in the logs for DNS resolution failures, refused connections, handshake failures, or authentication errors. Compare the same configuration on another network to help distinguish local network restrictions from a remote issue. You can also test another proxy in the same policy group. If only the speed test fails while browsing works, check the test URL and timeout setting. When contacting your provider, include the error type and time it occurred, but hide server credentials; a timeout screenshot alone isn’t enough.
Why do some apps or terminal commands connect directly even when the system proxy is on?
The system proxy provides a proxy address to apps that honor the setting; it does not transparently capture traffic. Some command-line tools read the HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY environment variables, while others only use their own proxy settings. Browser extensions may also override system settings. Confirm that the core is running, then test with an explicit proxy using curl -I -x http://127.0.0.1:7890 https://example.com, replacing the port with the one actually in use. If the explicit proxy works, check the app’s proxy source and bypass list. To capture traffic from apps that ignore the system proxy, consider TUN mode, but also check routes, permissions, and conflicts with other VPNs.
Windows Store apps can’t connect. How do I handle the UWP loopback restriction?
Some apps isolated by AppContainer cannot access a local loopback proxy. If a browser works but a specific app does not, check for a loopback restriction. First confirm that the affected app is using the local proxy. Then use the client’s loopback exemption tool, or run CheckNetIsolation LoopbackExempt -s in an administrator terminal to see the current exemption list. To add an exemption manually, run CheckNetIsolation LoopbackExempt -a -n= followed by the target app’s package family name—not the name shown in the Start menu. Grant access only to the apps that need it; don’t exempt every app. You can also try TUN mode as an alternative, though results depend on the app’s network behavior and routing configuration.
Android disconnects or drains the battery when the screen is locked. How do I check background activity?
Find the client in your system settings and check its battery usage, background activity, and auto-start permissions. Menu names vary by manufacturer. If it disconnects when the screen locks, allow background activity and check whether the VPN connection stays active. Also make sure no other VPN app is taking over the connection. If battery use is high, look for frequent reconnections, repeated subscription updates, or continuous debug logging; then compare battery use after disabling unnecessary connection tests. Don’t change every battery-saving option at once. Adjust one setting at a time and observe under similar network conditions. Weak signal, hotspot use, and heavy background traffic can also increase power consumption, so a high share of battery use by the client alone does not prove the core is malfunctioning.
Still need help pinpointing the issue? Follow the symptom-based troubleshooting steps →