Clash FAQs
and Troubleshooting

Import a subscription from the client’s Profiles page, then enable the profile and choose a proxy group. The client provides the window, menu bar and system integration; the mihomo core accepts connections, resolves DNS, matches rules and forwards traffic; a subscription supplies server settings and may also include proxy groups and rules. Installing the client alone does not provide a working proxy service. When troubleshooting, first determine whether the issue is with the client settings, core startup or subscription content instead of repeatedly reinstalling all three.

For everyday use, start with Rule mode, then check the Connections page to see which rule and proxy are actually being used. Rule mode follows the config to decide whether each connection goes direct or through a proxy. Global mode applies the global policy to connections that reach the core, but you still need to select an available proxy. Direct mode connects straight to the destination. Use Global mode for brief comparison tests; it does not capture app traffic by itself. If an app’s traffic never reaches the core, changing modes won’t help. When testing is done, switch back to Rule mode and reconnect to avoid results being affected by existing connections.

For apps such as browsers that follow system proxy settings, start with the system proxy. Consider TUN for apps that ignore those settings or for some UDP traffic. A system proxy changes the operating system’s proxy settings; TUN captures traffic through a virtual network interface and routes, and requires the relevant permissions. What happens when both are enabled depends on the client and its routing setup. Troubleshoot one traffic-capture method at a time, confirm connections appear in the log, then test combinations. Also check whether another VPN is controlling the default route.

On macOS, open About This Mac from the Apple menu. Choose the Apple silicon installer if it shows an Apple chip, or the Intel installer if it shows an Intel processor. On Windows, check System type in Settings; on Android, choose a build that matches the device architecture and the client’s requirements. Check the download page’s client notes and the publisher’s requirements, especially the minimum OS version. mihomo core builds are mainly for command-line, server and router use. For a graphical interface, choose a client with a window and profile management.

Open the client’s Profiles page and choose Add or Import. Paste the full subscription URL into the URL field, then set the downloaded profile as the active one. To import a local file, use the file import option or drag in config.yaml if the client supports it. After importing, check the profile name and any error messages, then choose a proxy group on the Proxies page. Button labels vary by client, but the steps are the same: import the profile, enable it and choose a proxy. Keep all credentials in the subscription URL intact, and never post it in a public forum.

Check whether the error message includes a line number. Then make sure the download is YAML that Clash or mihomo can read—not a login page, error page or format intended for another client. YAML uses spaces for indentation, and fields at the same level must align. When editing by hand, watch for the space after each colon and the nesting of list items. A plain Base64 list of proxies may not be a complete, usable config; ask your provider for a compatible subscription format. Keep a copy of the original file, make corrections and reload the profile. Don’t upload a config containing credentials to an unfamiliar conversion site.

Turn off TUN first. In the client settings, find the service mode, helper service or permission setup option, follow the prompts to grant system permissions, then enable TUN again. On Windows, this usually means installing and starting a background service with administrator privileges. On macOS, you may need to authorize a privileged helper; follow the client’s instructions. If it still fails, check the logs for permission, device or routing errors, and temporarily quit other VPNs before trying again. Don’t run all your apps with elevated privileges just to clear a permissions warning. On managed devices, check that your organization’s network and security policies allow these changes.

In the client settings, check the actual mixed-port and confirm the listening address is the local loopback address. If the port is already in use, quit the other proxy process or switch to a free port, then update any apps that use it. Terminal tools may not follow system proxy settings. Test with an explicit proxy using curl -x http://127.0.0.1:7890 https://example.com, replacing the port with the one in use. If you need environment variables, set them only for the terminal session that needs them and clear them after testing. Don’t expose the listener to your local network just to access it from your own device.

Check the proxy group type to see whether you need to choose a proxy manually or wait for an automatic test. select keeps your manual choice and works well for a fixed proxy. url-test picks a candidate based on the configured test URL and interval. fallback checks candidates in order and uses the first one that passes, making it more suitable for failover. Test results show connectivity to the specified URL, not how every service will perform. If a site won’t load, select one proxy manually for comparison, then check which proxy group the matching rule uses. This keeps automatic switching from changing the test conditions.

Save custom entries in the client’s overrides, config merge or additional rules section instead of editing a subscription file that gets downloaded again. Updates usually replace remote content, and whether local edits are preserved depends on the client. Put custom rules that need priority before the related general rules, and make sure any referenced proxy group exists. After saving, check the effective config and verify the match on the Connections page. If you switch clients, migrate your changes using the new client’s instructions; override options and merge syntax can differ.

Open the client’s Connections page and visit the site again. Find its domain or destination address and check the matched rule, proxy group and final proxy. If no new connection appears, first check whether system proxy or TUN is capturing traffic; don’t keep changing routing rules. After editing a rule, close the app’s existing connections before testing, since established connections usually won’t switch routes immediately. Browser caches, built-in app proxies and encrypted DNS can affect what you see. If needed, make a separate test request and check the DNS logs to confirm the domain was recognized correctly.

First confirm the issue occurs only in Fake-IP mode. Use the logs to identify the affected domain, add only the necessary domains to fake-ip-filter, save and reload the config, then reconnect the app. Filter behavior can also depend on settings such as fake-ip-filter-mode, so check the active config. For LAN devices, verify that private address routes and direct rules are correct. Switching DNS modes can leave stale DNS cache entries; restart affected apps and flush the system DNS cache. Don’t exclude large numbers of public domains, as this can change domain matching and routing behavior.

Check the device’s date and time, network connectivity and provider account status, then review the update log for the HTTP status and error details. A 401 often means credentials are missing or expired; a 403 may also indicate an access restriction. Check with your provider for the specific cause. For timeouts, determine whether the subscription URL is unreachable or the current proxy route is interfering with the download. If the client lets you choose the network path for updates, test both direct and proxied connections. Keep the last working config rather than deleting everything. Redact subscription URLs, credentials and server authentication details before sharing logs.

Select one proxy to test, then check the logs for DNS resolution errors, connection refusals, handshake failures or simple timeouts. Compare results on a different network. If the client’s test URL is unreachable, the check may fail even when some services still work, so test the actual site as well. Confirm the subscription is active and the device time is correct, and check whether security software or a firewall is blocking the core. If every candidate fails on the same network, start by checking the device and network route. If only a few fail, send your provider the error time and redacted logs.

Check the proxy settings for the operating system’s current network connection, and make sure the address and port match a running client. Then check whether a browser extension or separate proxy setting is overriding the system settings. If an explicit proxy request succeeds but no browser connection appears in the client, focus on how the browser is configured to send traffic. If internet access stops after quitting the client, the system may still be pointing to a port that is no longer listening. Turn off the stale proxy in network settings and try again. On macOS, check the network service in use; on Windows, distinguish user proxy settings from WinHTTP. Don’t change unrelated settings.

First confirm the affected app runs in an AppContainer and uses the system proxy set to a local loopback address. If the client provides a UWP loopback exemption tool, grant permission and select only the apps that need proxy access, then fully quit and reopen them. You can also use CheckNetIsolation LoopbackExempt -s in an administrator terminal to see existing exemptions. To add one, you’ll need the exact package family name. A loopback exemption only lets an app access a local proxy; it won’t fix subscription or DNS problems. TUN is a separate way to capture traffic and should be tested on its own. Follow your organization’s policies on managed devices.