How to Read Clash Logs: Common Errors and Troubleshooting

1. Open the core log and capture one complete failure

A client may have separate pages for application logs, core logs, and connections. Application logs mainly cover UI startup, profile downloads, and service management. Core logs show rule matching, DNS lookups, and proxy connections. The connections page shows active connections and their proxy chains. These views complement one another; they are not the same log.

Reproduce the issue with as few steps as possible

1. Open the client’s Logs or Core Logs page and note the current time, active profile, and proxy mode. Menu names vary by client.
2. Make sure the core log level is set to info. If you need more detail, temporarily switch to debug, apply the configuration, and reproduce the issue.
3. Close other apps that are actively using the network, then open just one page that fails. Note when you click it—for example, 14:32:08—and watch the logs for about 10 seconds.
4. Keep the error line and 5–10 lines before and after it. When you’re done troubleshooting, switch back to info to avoid accumulating large volumes of debug output.

# Merge into the top level of the current configuration; do not add duplicate fields
log-level: info

If you manage the configuration through a subscription, edits to the downloaded file may be overwritten the next time it updates. Use the client’s override or merge feature when available. If you must edit the file directly, back it up first and confirm that the reload succeeds. If parsing fails, the new settings may not have taken effect.

2. Understanding log levels and fields

A log level indicates the severity of a record; it is not a score for network quality. A warning from a background app retrying a request may have nothing to do with the page you’re testing. Conversely, seeing only info does not prove that the page loaded successfully.

Break a log entry into five parts

time="2026-09-15T14:32:08+08:00" level=info msg="[TCP] 127.0.0.1:53124 --> www.example.com:443 match DomainSuffix(example.com) using Web Proxy[Node A]"

• Time: 14:32:08+08:00 lets you line the entry up with the action you just took. When comparing across devices, account for the time zone.
• Protocol: [TCP] means this connection uses TCP. It says nothing about whether UDP is working.
• Source: 127.0.0.1:53124 is the local source address and ephemeral port. 53124 is not a listener port to enter in your proxy settings.
• Destination: www.example.com:443 is the requested destination and port, not necessarily the node address ultimately dialed in the error.
• Match and outbound: DomainSuffix(example.com) is the matched rule. Web Proxy[Node A] identifies the policy group and selected node.

An informational entry like this shows how the core handled the connection. It does not mean the TLS handshake, login, or page resources have all completed. If a timeout or handshake error follows, keep reading; don’t stop at “proxy matched.”

3. dial tcp timeout: Find where the timeout occurred

level=warning msg="[TCP] dial Web Proxy (match DomainSuffix/example.com) 127.0.0.1:53124 --> www.example.com:443 error: dial tcp 203.0.113.20:443: i/o timeout"

dial tcp means a TCP connection is being established; i/o timeout means a step took longer than the allowed time. Some entries say connect: connection timed out, or wrap the error as context deadline exceeded. These indicate that a wait failed, but don’t by themselves tell you whether DNS, the remote service, or a local firewall is responsible.

Check the final IP address and port

In this example, the requested destination is www.example.com:443, but the address actually dialed is 203.0.113.20:443. If that matches the node’s server and port, start by checking the connection between your computer and the node. If the request uses DIRECT, check the direct route to the destination instead. With chained proxies, account for each hop in the actual chain.

1. Check the node configuration: Make sure the subscription hasn’t expired and that the node’s hostname, port, and protocol match the server settings. Don’t assume the website’s 443 is also the node port.
2. Change one variable at a time: Leave the rules and DNS unchanged, switch to another known-good node, and try the same destination again.
3. Compare networks: If possible, try a mobile hotspot. If the same node times out only on a particular Wi-Fi network, investigate that network’s outbound restrictions first.
4. Check the local network path: Look for conflicts involving firewalls, other VPNs, virtual adapters, or TUN routes. Don’t disable all security protections as a first step.

On Windows, use Test-NetConnection in PowerShell to check TCP reachability. The address below is reserved for documentation; use the actual hostname and port from your node configuration, not the example address.

Test-NetConnection -ComputerName 203.0.113.20 -Port 443

A successful TcpTestSucceeded only means that this TCP connection was established. It doesn’t verify the proxy protocol, credentials, or UDP forwarding. Node latency tests have the same limitation: success against one test URL doesn’t mean every domain is reachable.

4. connection refused: Determine whether the local or remote port was refused

dial tcp 127.0.0.1:7890: connect: connection refused

connection refused usually means the connection was explicitly rejected. Common causes include no service listening on the destination port or a firewall actively rejecting the request. Unlike a timeout, which means no expected response arrived in time, a refusal often comes back quickly.

Address is 127.0.0.1: Check the proxy listener

If the error comes from a browser, command-line tool, or another app and the address is 127.0.0.1:7890, first confirm that the core is running and actually listening on port 7890. The client may have switched to 7897 while the system proxy still points to the old port. Don’t substitute the source’s ephemeral port here.

# Example fields from the current configuration; the port must match the app settings
mixed-port: 7890
allow-lan: false

mixed-port accepts both HTTP and SOCKS5 proxy connections. When entering the proxy settings in an app, still select the correct protocol; a mixed port doesn’t mean you can choose any protocol. Check listener status on Windows, or use the appropriate port-checking command on macOS and Linux:

# Windows PowerShell
Get-NetTCPConnection -LocalPort 7890 -State Listen

# macOS
lsof -nP -iTCP:7890 -sTCP:LISTEN

# Linux
ss -lntp 'sport = :7890'

Address is a remote node: Check the server listener and subscription

If the refused address is the node’s IP and port, check whether the server is still listening, whether its port changed, and whether the subscription is up to date. Changing the local mixed-port repeatedly won’t fix a refusal at the remote port. If startup logs show address already in use, a local process has occupied the port. Identify it first, then decide whether to stop the conflicting service or change the port consistently.

5. DNS resolution failures: Distinguish the destination domain from the node domain

lookup www.example.com: no such host
dns resolve failed: all DNS requests failed
read udp 192.168.1.8:53012->192.168.1.1:53: i/o timeout

no such host commonly means the system resolver couldn’t find the hostname, but check the spelling, DNS upstream, and response before drawing conclusions. all DNS requests failed is a summary error; look earlier in the logs for the specific cause. A UDP 53 timeout means a query to the relevant DNS server did not receive a timely response.

Check the resolution path at three levels

1. Which hostname failed? A website domain failure affects access to that site. If the failed name is the node’s server hostname, the proxy tunnel may not be able to come up at all. The troubleshooting order is different in each case.
2. Which resolver is being used? Check whether core dns is enabled, whether the app uses its own secure DNS, and whether TUN captures system DNS requests.
3. Can the upstream be reached? Traditional DNS, DoH, and DoT use different network paths. DoH uses HTTPS, but that doesn’t guarantee it’s reachable on your current network.

The system command nslookup www.example.com usually queries the DNS server configured for the system. If it succeeds, that only confirms that particular resolution path works; it doesn’t prove that Clash core DNS or your browser’s built-in DoH is working. When comparing results, note which server handled each query rather than just whether an IP address was returned.

In Fake-IP mode, it can be normal for an app to receive a mapped address in the 198.18.0.0/16 range; the exact range depends on fake-ip-range. Don’t assume resolution is broken just because the address doesn’t look like a public IP, and don’t use the mapped address alone to draw conclusions about public network reachability.

After changing DNS, the app, operating system, and core may each retain their own cache. Clear the relevant caches using the method supported by your client, close existing connections, and test again. An old cached result doesn’t prove the new configuration is active.

6. Trace a request back from its matched rule to find the wrong outbound

In Rule mode, rules are generally checked from top to bottom in rules, and the matched rule determines the policy. In Global mode, check the selected global policy instead. In Direct mode, don’t expect regular proxy rules to handle requests as they do in Rule mode. Confirm the current mode before troubleshooting so you don’t keep changing settings that aren’t part of the decision.

mode: rule
rules:
  - DOMAIN-SUFFIX,example.com,Web Proxy
  - GEOIP,LAN,DIRECT
  - MATCH,Web Proxy

This example assumes the existing proxy-groups contains a group named “Web Proxy” and that the core supports the rule type shown. It’s a rule snippet, not a complete configuration. MATCH is the catch-all rule and should come after rules that need to be evaluated first.

Check the rule, policy group, and final node in order

• Did the expected rule match? If a request to example.com shows MATCH, check the actual hostname, subdomains, rule order, and whether the configuration reloaded.
• Does the match make sense? If the result is DIRECT, check whether an earlier direct rule caught the request before concluding that the node is at fault.
• Is the right policy group selected? The same group may choose DIRECT, another group, or a specific node. Auto-test and failover groups may also change the outbound dynamically.
• Are only some resources failing? The main page, images, and login API may use different domains. Checking only the hostname in the address bar can miss the resource that actually failed.

For example, the main page may use “Web Proxy” while the login API matches a direct rule. The result can look like “the page loads, but login keeps spinning.” Find the request time from the login attempt, identify its destination hostname, and, if needed, use the browser’s Network panel to pinpoint the failed request before checking the logs.

Temporarily switching to Global mode can help you compare behavior, but it isn’t a final fix. If Global mode works and Rule mode doesn’t, go back to the rules and DNS path. After changing settings, close existing connections before retrying: active connections may continue using the old outbound and won’t automatically reconnect when rules change.

7. Additional checks for TLS, UDP, and configuration errors

Setting udp: true in the configuration can’t give UDP support to a server that doesn’t have it. For game or voice issues, check the entire path: client entry point, node protocol, server, and outbound network. Similarly, a browser using QUIC may generate UDP-related entries; a successful TCP connection can’t explain every symptom.

If a certificate error occurs during the node handshake, check the node’s server name and protocol settings. If it occurs while updating a subscription, check the subscription site and the system trust chain. Both errors may contain x509, but they happen at different stages of the connection.

8. Sharing troubleshooting details: Keep context, remove sensitive data

A useful troubleshooting report doesn’t need to be long, but it should connect your actions to the relevant connection. These details are more likely to lead to an accurate diagnosis than simply saying “it timed out”:

1. Environment: OS and client versions, plus the core name and full version number. Copy these from About or the startup log rather than just saying “latest.”
2. Traffic entry: System proxy or TUN, current mode, local listening port, and whether one app or all apps are affected.
3. Reproduction: When the issue occurred, which feature failed, the policy group and node selected at the time, and whether you had just updated the subscription or configuration.
4. Evidence: Relevant log context, rule match entries, and comparisons after switching nodes or networks.

For the final retest, follow the same order: confirm the request reaches the core, verify the rule and outbound are as expected, then check DNS, connection setup, and completion of the application-layer request. Change one thing at a time and record the result. This helps distinguish a real fix from a temporary recovery and makes it easier to restore a working configuration after a subscription update.