How to Read Clash Logs: Common Errors and Troubleshooting Steps

Start by identifying where the failure occurs, then change the configuration. Switching nodes whenever you see a red log entry often sends you down the wrong path: a local port may not be listening, a domain may not resolve, a rule may select the wrong route, or a remote handshake may fail. All can look like “the webpage won’t load,” but each calls for a different fix.

This guide covers the Clash and Clash Meta (now called mihomo) cores. Clients may reformat logs, and the same error can have different prefixes. The examples below illustrate log structure; they are not records from a specific device. When troubleshooting, use your own timestamps, destination addresses, and actual routes.

1. Capture a complete failure

Open the client’s “Logs” page and clear any search terms. If the interface offers both a display-level filter and a core log-level setting, note the difference: a filter only hides existing entries; it cannot restore debug details the core never logged. Use info for routine use, and switch briefly to debug when an issue is difficult to reproduce.

1. Note the client name and version, plus the core name and version. The client version is not the core version.
2. Check the active configuration, operating mode, and system proxy and TUN settings, then note the local time.
3. Keep the existing logs. Clear the display or note where you’ll start, then visit the affected URL once.
4. Copy the failure entry and about 10 lines before and after it. If several connections appear, distinguish them by destination domain, port, and source port; don’t assume nearby entries are related.

2. Read log levels and connection fields

These are common core log levels. A client may display warning as WARN or use a localized label. A level indicates the severity of an entry; it doesn’t tell you that the failure happened locally. For example, a timeout from a website’s backend may also be logged as a warning.

time="2026-09-11T10:20:30+08:00" level=info msg="[TCP] 127.0.0.1:53124 --> example.com:443 match DomainSuffix(example.com) using PROXY[Node A]"

• time: The time the entry was recorded. Check the system time zone so you don’t mistake an old error for the current request.
• [TCP]: The transport protocol used for the connection; UDP requests have a corresponding label.
• 127.0.0.1:53124: The source of this connection, not the core’s proxy listening port.
• example.com:443: The request destination. Port 443 is commonly used for HTTPS, but the port alone doesn’t confirm the application protocol.
• match: The rule that actually matched, not the one you expected to match from the configuration.
• using: The policy group and selected route. A group named PROXY doesn’t guarantee that its current selection is a proxy node.

This entry shows that the core matched a rule and selected a route for the connection. It does not mean the webpage loaded successfully. The connection, TLS handshake, or application response may still fail. Check failure entries from the same visit as well.

3. dial tcp timeouts: identify the destination first

dial tcp 203.0.113.10:443: i/o timeout
dial tcp 127.0.0.1:7890: connect: connection refused

The first line indicates that a TCP connection attempt didn’t complete within the timeout. The 203.0.113.10 address in this example is reserved for documentation and must not be used for testing. In a real log, this address may be the website’s IP or the proxy server’s IP; check the error prefix and selected route to tell which. When using a proxy, a “dial failure” doesn’t necessarily mean the website’s server is at fault.

Check each address type

1. If the address is a proxy server: Keep the test URL the same and switch only one node. If just one node repeatedly times out, check its address, port, and service status first; don’t start by changing all your DNS settings.
2. If the address is the destination website: Check whether the connection is actually going DIRECT. If rules for destinations in and outside mainland China are reversed, a destination that should use the proxy may connect directly.
3. If the address is a loopback address: Check that the local proxy is listening on that port. 7890 is a common setting, but use the value in your active configuration and client interface.

connection refused usually means the connection was explicitly rejected, often because no process is listening or a firewall actively denied it. i/o timeout means the connection timed out while waiting. These errors aren’t interchangeable, and a single timeout doesn’t prove a node is permanently unavailable.

Narrow it down with an explicit proxy request

Once you’ve confirmed that the mixed proxy port is actually 7890, run the command below. On Windows, use curl.exe to avoid conflicts with the curl alias in older versions of PowerShell.

curl --noproxy "" -v --connect-timeout 10 --max-time 20 --proxy http://127.0.0.1:7890 https://example.com/

Here, 10 seconds is the connection timeout and 20 seconds is the overall request timeout; neither measures network speed. The command explicitly uses the local proxy, making it easy to compare with the browser. If the command works but the browser doesn’t, check the browser’s proxy extensions, system proxy, and app-specific network settings. If no matching connection appears in the logs, first check the command’s port and the log filters.

4. DNS failures: distinguish the three domains

Before troubleshooting a DNS error, ask which name failed to resolve: the destination website, the proxy server, or the DNS upstream itself? Each failure occurs at a different stage. If the proxy server’s hostname won’t resolve, trying another website usually won’t help—the route itself isn’t ready.

lookup example.com: no such host
lookup example.com: i/o timeout

no such host usually indicates a nonexistent domain or a negative response from the resolver. i/o timeout more often means no response arrived in time. Check which DNS server the error names and read it in context. If you see all DNS requests failed, none of the upstreams tried for that lookup succeeded; it doesn’t mean that “all nodes are broken.”

• Check the domain spelling, then review fields such as dns.enable and nameserver in the active configuration.
• Check that the DNS upstream is reachable. With encrypted DNS, you also need to consider upstream hostname resolution, connectivity, and certificate validation—not just UDP port 53.
• If your mihomo configuration uses proxy-server-nameserver, make sure it can resolve proxy node hostnames without relying on a proxy route that hasn’t been established yet.
• Replace just one upstream and compare results for the same domain before and after the change. Don’t change DNS, nodes, and rules all at once.

In fake-ip mode, a synthetic address in the 198.18.0.0/16 range doesn’t immediately indicate DNS poisoning. Check the fake-IP mapping, whether traffic returns to the core, and whether the domain information is available for rule matching.

5. Unmatched rules: trace back from the actual route

“Rule not matched” often isn’t an explicit error. More often, the connection log shows a rule you didn’t expect. First check that the client is in Rule mode. Global and Direct modes don’t use routing rules in the same way, so editing the rules file may not have the effect you expect.

rules:
  - DOMAIN-SUFFIX,example.com,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

This snippet illustrates rule order and assumes the configuration defines a policy group named PROXY. Rules are generally checked from top to bottom, and the first match determines the policy. Put MATCH last as a fallback. If it appears before your domain rules, those rules will never get a chance to handle the connection.

A MATCH rule isn’t necessarily an error

Falling through to a fallback is normal when no more specific rule matches. If a domain should match a dedicated rule, check the active configuration, rule spelling, remote rule-set status, and whether the log still includes the domain. When only the destination IP is available, domain-based rules may not match as expected; sniffing can’t reliably recover a domain from every connection.

• DOMAIN matches an exact domain; DOMAIN-SUFFIX matches a domain and its subdomains. Don’t include a full URL or path.
• RULE-SET requires a matching rule-providers name, and the provider must be compatible with the rule set’s type and content format.
• Check that the core supports features such as GEOSITE. Don’t assume a mihomo configuration will work with every older Clash core.
• Before editing a subscription-generated configuration, check how the client handles overrides. Changes to a temporary file may be overwritten the next time the subscription updates.

Finally, open the policy group and check its active selection. Even if the log shows a match for PROXY, selecting DIRECT within that group still sends the connection directly. Check the rule name, policy group, and actual route separately.

6. Common misdiagnoses: listeners, TLS, and TUN

If a port is already in use, run netstat -ano | findstr :7890 on Windows to check related listeners and PIDs, or lsof -nP -iTCP:7890 -sTCP:LISTEN on macOS or Linux. Identify the process before closing a duplicate instance; don’t terminate an unfamiliar system process. If you change the port, update the system proxy and test commands too.

For certificate errors, don’t treat disabling certificate verification as a general fix. First correct the system clock, then identify whether the error comes from a subscription download, DNS upstream, proxy server, or destination website. Certificates for different stages aren’t interchangeable; changing the wrong setting won’t help and can weaken connection security.

TUN captures traffic; it doesn’t automatically fix an unreachable node or an expired certificate. Try disabling TUN and use an explicit HTTP proxy command to test the core’s route. If the explicit proxy works but TUN doesn’t, focus on service permissions, the virtual network adapter, routes, and DNS capture. This comparison preserves more useful evidence than reinstalling the client and changing every rule at once.

7. A repeatable workflow for tracing errors back to configuration

1. Confirm the core is running. Check that the configuration loaded and the proxy port is listening. Don’t investigate website rules until startup errors are resolved.
2. Confirm the request reaches the core. Use the same URL for a single visit and check for a matching destination. Rule out an empty log caused by filters.
3. Confirm the mode and matched rule. Note whether the mode is Rule, Global, or Direct, along with the rule shown in the log.
4. Confirm the actual route. Expand the policy group to see the final node or DIRECT selection; don’t rely on the group name alone.
5. Identify the failure stage. Distinguish DNS resolution, TCP connection, TLS handshake, and application response, then check the relevant configuration field.
6. Change one thing at a time. Keep a copy of the original configuration, reload, and start a new connection with the same request to compare results. Existing connections may continue using their original route.
7. Retest, then restore the log level. Repeat the same request several times to confirm the fix is stable, then switch from debug back to info to avoid accumulating overly detailed traffic records.

To check configuration fields, see the configuration reference. When posting a question to the community, include the core version, a redacted configuration snippet, reproduction steps, and logs from the relevant time window. That’s much more useful than “the proxy doesn’t work” and helps narrow the issue down to a port, rule, or DNS upstream.