FAQ / Usage & Troubleshooting

Clash FAQ

From importing subscriptions and routing traffic to node timeouts: identify where the problem occurs, then check the relevant settings and logs.

BASICS

Basics

Understand the client, core, local ports, and remote nodes.

View configuration fields
What’s the difference between a Clash client and the mihomo core?

The client provides the interface and system integration; the core reads the configuration, matches rules, and establishes connections. Installers are usually published by the client project, but supported fields depend on the core and version it actually runs. If you see an “unknown field” error, check the core version in the client’s About page or startup log, then consult the documentation for that version. Updating the interface doesn’t necessarily update the core. The same configuration can also behave differently on two devices if their core versions differ.

How do Rule, Global, and Direct modes differ?

Use Rule mode for everyday browsing. The core checks rules in configuration order and applies the policy assigned to the first matching rule. Global mode is useful for a quick comparison: select a known-good proxy for the global policy, then retry the same request. Direct mode sends traffic that has already entered the core straight to its destination, but it doesn’t turn off the system proxy or TUN. To test whether an app can connect without going through the core, disable the relevant traffic capture method separately and start a new connection.

Is mixed-port the port used by a remote node?

No. mixed-port is the local port the core listens on for HTTP and SOCKS proxy connections. The port in a node’s configuration is the remote server’s port. When configuring an app manually, 127.0.0.1 is a common address; use the listening port shown in your current configuration or client, rather than assuming it’s always 7890. If you only need local access, keep LAN access disabled so other devices on the network can’t use your proxy.

Can subscription URLs, YAML files, and node links be used interchangeably?

They serve different purposes. A subscription URL points to remote content that the client can fetch again whenever needed. A local YAML file is a standalone copy and usually won’t sync with its original subscription after import. A single node link typically describes one outbound connection, not a complete configuration with local ports, proxy groups, and rules. If you only have a node link, check that your client supports importing individual nodes; don’t paste it into an importer that expects a full configuration. Subscription URLs may contain access credentials, so don’t share them in public screenshots or support tickets.

SETUP

Setup

Choose the right installer, confirm the configuration is loaded, then enable traffic capture.

View import steps
What system requirements should I check before installing a client?

Check your operating system version, processor architecture, and package format first. On desktop systems, look in System Information to see whether your device is x64 or ARM64. On a Mac, use About This Mac to check whether it has an Intel processor or Apple silicon. On Linux, make sure the package format matches your distribution; similar-looking filenames don’t guarantee compatibility. Before updating, verify that the installer comes from the client’s release channel. If your system reports that it’s unsupported or refuses to launch the app, check the minimum OS version and architecture instead of disabling system-wide security settings.

How can I confirm that an imported subscription is active?

A successful import doesn’t necessarily mean the configuration is active. In the client’s configuration page, choose “Import from URL” or the equivalent, save it, wait for the download to finish, then select the imported configuration. Open the proxy page and check that its proxy groups come from the new configuration. Look for parsing or startup errors in the logs. If the file appears in the list but the proxy page still shows the old groups, confirm which configuration is active and check whether the new file failed to load. Finally, visit a reachable site and use the connections page or logs to verify that the request reached the core.

TUN won’t start and reports insufficient permissions. What should I do?

First, make sure your client supports TUN on your operating system, then check how it handles authorization. Desktop clients may require you to install and start a proxy service or grant administrator access the first time you enable TUN. On Linux, device access or network management permissions may also be required; follow the guidance for your distribution and client. Mobile clients that use the system VPN interface usually ask you to approve a connection request in a system prompt. If TUN still fails after authorization, check the service status and the first startup error, then see whether another VPN or virtual network adapter is managing your routes.

How can I keep my local configuration and overrides when upgrading a client?

Back up your configuration and overrides before changing client versions. Use the client’s export feature to save your local YAML, override files, and any settings you want to keep. If there’s no export option, check the client’s documentation to find its configuration directory. Store backups somewhere only you can access, and treat remote subscription URLs as credentials. After updating, select the original configuration and check that its proxy groups and rules still behave as expected before enabling traffic capture. If parsing errors appear, save the error details and check whether the relevant fields are supported by the old and new core versions.

USAGE

Usage Tips

Check how requests reach the core, which rules they match, and which resolver handles DNS.

View rule syntax
Should I enable the system proxy or TUN first?

Start with the system proxy if you only need browsers or apps that follow system proxy settings to use a proxy. It provides those apps with a local proxy address, but doesn’t route traffic from every program through the core. If an app ignores the system proxy, check its own proxy settings or use TUN if your client supports it. TUN captures traffic at the routing layer and may affect LAN access, corporate VPNs, and DNS. For your first test, enable only one traffic capture method. Confirm that the same request appears in the logs before changing what traffic is captured.

Why do only UWP apps need loopback exemptions?

Some apps running in Windows app containers are restricted from accessing loopback addresses by default, so they may not be able to connect to a proxy at 127.0.0.1. A common symptom is that a regular desktop browser works on the same port, while a containerized app can’t connect. If your client offers a UWP loopback management option, follow the system’s authorization prompts and grant an exemption only to apps that have the problem and need a local proxy. Close and reopen the app before testing, and don’t exempt every app in the list. If the issue persists, check whether the app uses the system proxy.

Why isn’t a rule matching even though it’s in my configuration?

Make sure Rule mode is active, then check which rule the connection actually matched. The core evaluates rules in order, so a broad rule placed too early can prevent more specific rules later from taking effect; MATCH is usually the fallback at the end. Compare the destination in the logs with the domain in your configuration, and make sure the proxy group name matches exactly. If the logs show only a destination IP, check whether your traffic capture method provides domain information to the core. Change one thing at a time, save and reload the configuration, then test with a new connection rather than reusing an existing browser connection.

Does enabling DNS in the configuration make every app use it?

Not necessarily. Enabling the core’s DNS features doesn’t mean every DNS query on your system will pass through it. First, check how the app you’re testing resolves domains: through the system resolver, the browser’s own encrypted DNS, or queries captured by the client under TUN. Note the client mode and browser settings during testing. Change one setting at a time, retry with a fresh query, and check the logs. A single lookup or returned IP isn’t enough to tell whether the system DNS was bypassed; browser caching and per-domain resolution policies can affect the result.

DIAGNOSIS

Troubleshooting

Start with the first error, then determine whether the problem is the subscription, local proxy, or remote connection.

Check system proxy settings
How can I tell whether a failed subscription update is due to an invalid URL or a network issue?

Check the update log to see where the request failed. For a 401 or 403, verify your account status, URL permissions, and whether the provider has changed the subscription address. For a 404, first check whether you’re still using an old URL. If the log shows a DNS resolution failure, connection timeout, or certificate error, troubleshoot your network, system clock, and the client’s subscription update path before assuming the subscription has expired. If content was downloaded but YAML parsing failed, check whether the response was actually a login or error page. Keep your current working configuration until the new subscription loads successfully.

How should I troubleshoot timeouts on all Clash nodes versus just a few?

If every node times out, check what they have in common. If only a few do, investigate those nodes individually. First, make sure the device can connect to the internet, the active configuration is loaded, and the test target is reachable on your current network. If a website still opens through a node, a speed test timeout alone doesn’t mean that node is unusable. If both tests and real requests fail, check the first connection error to distinguish DNS resolution failures, remote connection timeouts, and handshake failures. For isolated node issues, compare affected and working nodes on the same device and against the same target, then decide whether to refresh the configuration or contact your provider.

Why isn’t an app using the proxy even though the system proxy is on?

Use the connections page or logs to tell whether the request never reached the core or reached it and matched a Direct rule. If there’s no record, check that the system proxy address and port match the core’s listening settings. Then check whether the app uses its own proxy, is on the system bypass list, or has had its proxy settings overridden by other software. If the request appears as DIRECT, check the mode and rules instead of repeatedly toggling the system proxy. After changing settings, restart the app or make a new connection so an existing connection doesn’t make it look as if nothing changed.

The client says a port is already in use at startup. What should I do?

Check the startup log to identify whether the conflict involves the mixed port, the controller port, or another listening port. Then use your system’s network monitoring tools to identify the process using it. Common causes include an old client still running in the background or two clients trying to use the same port. Don’t force-quit a process if you’re unsure what it does. You can close a confirmed old instance or assign the current client an unused port. If you change the mixed port, update the system proxy and any apps configured with a manual proxy, then restart the core and confirm that it’s listening successfully.

Download Clash