Set up a reproducible test

First, pause automatic node switching and stick with one node, one test URL, and one traffic-capture method. “Connected” usually means the core is running or the system proxy or virtual adapter is enabled. It doesn't confirm that browser traffic is reaching the core or that the remote node can complete a TLS handshake with the target site.

  1. Note the current configuration name, proxy mode, selected group, and whether the system proxy and TUN are enabled. Never share your full subscription URL.
  2. Save a copy of the current configuration. Change one setting at a time, then decide whether to keep or revert each change after testing.
  3. Quit other proxy clients and VPNs. Ask your administrator to check security software or network policies on managed devices; don't disable protection yourself.
  4. Open the client's connections and logs, and start at the info level. If you temporarily switch to debug, remember that logs may include visited domains and local network details.
  5. Quit and reopen the browser to avoid reusing existing connections. Use the same URL for every comparison test.

1. Make sure the system proxy points to the right port

For a browser baseline, enable the system proxy and leave TUN off. The system proxy affects apps that follow system proxy settings; it doesn't capture every process. Games, command-line tools, browser extensions, and apps with their own proxy settings may take a different route.

Check system settings and browser extensions

  • Windows 11: Go to Settings → Network & internet → Proxy → Manual proxy setup and verify the proxy address and port. An automatic setup script and a manual proxy can both be configured, so confirm which settings are actually in effect.
  • macOS: Go to System Settings → Network → your current connection → Details → Proxies. Check that the web proxy and secure web proxy point to the address the client is listening on.
  • Browser: Temporarily disable proxy-related extensions and check for separate proxy settings or bypass lists. Incognito mode doesn't necessarily disable every extension.

A common local address is 127.0.0.1. Use the port in the active configuration; 7890 is not a universal default for every client. The YAML snippet below illustrates what the fields do. It isn't a complete configuration, so don't replace your subscription settings with it:

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

mixed-port accepts both HTTP and SOCKS connections. A socks-port alone cannot be entered as an HTTP proxy. The common 9090 value for external-controller is a management API port, not an entry point for web traffic. You don't need to enable “Allow LAN” to troubleshoot a browser on the same device.

Test the local proxy directly, bypassing system settings

The Windows commands below explicitly set an HTTP proxy, helping distinguish a system settings problem from a proxy connection problem. If your port isn't 7890, change it in the command first. On macOS and Linux, use curl and replace NUL with /dev/null.

curl.exe --noproxy "" --proxy http://127.0.0.1:7890 --connect-timeout 10 --max-time 20 -o NUL -sS -w "HTTP=%{http_code}\n" https://example.com/
  • Explicit proxy works, browser doesn't: Check the system proxy, browser extensions, and proxy bypass settings before changing nodes.
  • Immediate connection refused on the local port: Check that the core is running, the port is correct, and the listening process belongs to the client you're using.
  • Connection established, then times out: Check the logs for the node connection, DNS lookup, or target-site request. A timeout alone doesn't prove the port is at fault.

An HTTP status code means the request received an HTTP response; 403 or 451 may still indicate a site policy restriction. To confirm the request used the intended proxy, also check the outbound chain in the connection log.

2. Check for port conflicts and core startup failures

If the system proxy is set but the core failed to start because of a configuration error, the browser may send requests to a port with no listener. Check the logs for startup errors—such as a failed bind, configuration parse error, or missing policy group—before changing ports.

Find the listening process on Windows

Run these commands in PowerShell. The first checks the listening state and process ID; the second looks up the process using OwningProcess from the results. Replace the example ID 1234 with the actual value.

Get-NetTCPConnection -LocalPort 7890 -State Listen
Get-Process -Id 1234

On macOS, run lsof -nP -iTCP:7890 -sTCP:LISTEN. If another client is listening, quit it normally before starting the client you want to use. Don't terminate an unknown system process just because its port conflicts.

  • Nothing is listening: Check that the core is running, the active configuration is valid, and the port type is correct. Confirm the setting is actually enabled in the client.
  • The port is held by an old process: Quit duplicate instances and, if needed, use Task Manager to check whether the old process is still running.
  • After changing the port: Update the system proxy and any in-app proxy settings too. Otherwise the client may listen on 7891 while the browser still connects to 7890.

The subscription file may differ from the configuration actually in use. Client overrides, merged configurations, and GUI settings can all change the listening port. Check the runtime configuration and listening process. See the port configuration guide for details.

3. Isolate TUN permissions and routing issues

If the system proxy works but enabling TUN breaks access, focus on the virtual adapter, routing, and DNS interception. TUN passes IP traffic to the core and can cover apps that ignore system proxy settings, but it requires core support and permission to create an adapter and change routes.

  1. Turn off the system proxy, enable only TUN, and relaunch the app you're testing. This avoids the confusion caused by stacking two traffic-capture methods.
  2. Install or start service mode as required by your client, and approve the requested system permissions. Windows often uses a background service for privileged operations; macOS may require approval for a helper app; Linux typically needs appropriate network management permissions.
  3. Check the logs for virtual adapter creation failures, permission errors, or failed route additions. An enabled toggle doesn't mean traffic is being captured if initialization failed.
  4. Disconnect other VPNs and test again. When multiple virtual adapters compete for the default route, node traffic can be routed back into the tunnel, creating a loop.
  5. If the problem starts after waking from sleep or switching Wi-Fi networks, restart the client's core, re-establish TUN, and check that the routes are back in place.

Don't change the TUN stack, enable IPv6, modify the MTU, and switch DNS all at once. If transfers stall only with large files or some HTTPS sites, investigate the MTU after confirming basic connectivity. It's not the first thing to change when no websites load.

4. Tell system DNS apart from core DNS

If you see no such host, lookup failed, or a DNS timeout, first identify which layer is doing the lookup. Your browser may use Secure DNS, the OS has its own resolver, and the Clash core may resolve destination domains and proxy node domains separately. Changing system DNS won't necessarily change how the core resolves names.

Check DNS queries before clearing caches

On Windows, run the command below to see the result from the system's DNS path. This doesn't prove that the browser and core use the same DNS resolver:

nslookup example.com
ipconfig /flushdns

The second command only clears the Windows DNS client cache. The browser, core, and upstream resolvers may each have their own caches. After changing settings, restart the core using the method supported by your client, then reconnect the browser.

  • Node server uses a hostname: The node's hostname must be resolved too. If the upstream resolver can only be reached through a proxy that isn't up yet, startup can get stuck in a dependency loop. Check how the node hostname is resolved.
  • Using DoH: A DNS URL starting with https:// still depends on network connectivity and certificate validation. Check the system clock and how the resolver's hostname is resolved initially.
  • Browser uses Secure DNS: Temporarily switch to the system resolver for comparison. If that fixes the issue, check the rules for browser DNS traffic instead of leaving an unknown setting in place.
  • Only IPv6 destinations fail: Check local IPv6 connectivity and support along the proxy chain. You can temporarily disable the relevant IPv6 option for comparison, but note what you changed and verify it again after testing.

A Fake-IP address doesn't by itself indicate a DNS error

In Fake-IP mode, DNS results may fall within the configured synthetic address pool; a common configuration uses 198.18.0.1/16. The core maps domains to synthetic addresses and handles subsequent connections. Seeing 198.18.x.x doesn't mean the domain was resolved incorrectly, and a simple ping can't tell you whether web proxying is working.

The key questions are whether traffic to the synthetic address still passes through the same core and whether the mapping is still valid. If an app gets a Fake-IP address and bypasses TUN, the connection may fail. For LAN discovery, printers, or apps that require real addresses, configure fake-ip-filter as needed rather than excluding every domain. See the address and GeoIP guide and the glossary for background.

5. Check the routing rule and outbound node in connection logs

If the request has reached the core, check the connection list for its destination domain, matched rule, policy group, and final node. In Rule mode, rules are evaluated in order, and the first match usually determines the outbound route. A proxy group named “Auto” doesn't guarantee that its current selection is working.

Briefly compare Rule and Global modes

  1. Keep the current node and open the target site in Rule mode. Note the matched rule and outbound route.
  2. Temporarily switch to Global, explicitly select the same node in the GLOBAL group, and establish a new connection.
  3. If the site works in Global but not in Rule, check whether the rule sends it to DIRECT, REJECT, or another unavailable policy group.
  4. Switch back to Rule after testing. Global is a diagnostic tool, not a permanent fix for all traffic.

Rule order matters. A new domain rule placed after the catch-all MATCH usually won't take effect because an earlier rule has already handled the request. For lasting changes, use the override or rule-merge options supported by your client. Direct edits to generated subscription files may be overwritten on the next update. See the rule-based routing guide for details.

6. Check the node and target website

A successful latency test only shows that one probe completed within its timeout; it doesn't mean the target website is reachable. For example, a list may show 180 ms while the page times out after 20 seconds. There's no contradiction: the probe URL, connection protocol, exit restrictions, and target service may differ. These numbers are examples, not measured node data.

  • All nodes fail: Check whether the subscription has expired, the account has run out of data, the current configuration is enabled, or the provider has announced maintenance.
  • Only one node fails: Switch to another node in the same subscription and try the same destination. Don't change DNS at the same time, or you won't know which change helped.
  • Only one website fails: Check the site's status and regional restrictions. If the node can reach other HTTPS sites, don't assume the local port is the cause.
  • Authentication or handshake error: Check that the subscription is up to date, the node credentials are valid, and the core supports the protocol and its parameters.
  • Certificate error: First check the system date, time zone, and certificate setup. Don't disable certificate verification to hide the problem.

Testing on Wi-Fi and a mobile hotspot can help isolate the issue: use the same client, node, and URL on both networks. If only the current network fails, check its access restrictions, UDP support, and DNS path. Hotspot testing uses mobile data, so keep an eye on usage.

Choose the next step based on what you see

What you observe Check first Next step
Explicit proxy works, browser fails System proxy or browser-specific settings Check the address, port, and extensions; reconnect the browser
Connection refused on local proxy port Core startup and listening status Check startup logs and the listening process, then sync the port settings
System proxy works, TUN fails Adapter permissions, routes, and DNS interception Enable TUN by itself and check initialization logs
Global works, Rule fails Matched rule and policy group outbound Keep the same node for comparison and fix the misfiring rule
DNS lookup errors keep appearing in logs DNS paths in the OS, browser, and core Identify the failing layer; check upstream connectivity and startup dependencies
Only one node or website fails Node status and destination access restrictions Keep other settings unchanged; compare another node or network

Still not working? Collect a minimal diagnostic report

When reporting the issue to a maintainer, include your operating system, client and core versions, when the problem occurred, proxy mode, traffic-capture method, and steps to reproduce it. Include only the relevant logs from about 30 seconds before and after the failure. Also say whether “explicit proxy works,” “turning off TUN fixes it,” and “Global mode works.” These details are more useful for troubleshooting than a screenshot that only says “Connected.”

Before sharing logs, remove subscription tokens, node passwords, controller API secrets, and any unnecessary personal browsing history. When you're done troubleshooting, revert temporary changes, turn off debug logging, and make sure the system proxy points to the client that's still running. For other common issues, see Troubleshooting. For subscription setup and importing a configuration, see the subscription import guide.