Reading Clash Logs: What Common Error Messages Mean

Why logs are the first clue in troubleshooting

When a page won't load, a subscription stops working, or a specific app can't connect, most people's first instinct is to switch nodes or restart the client, then give up after a few tries. But the answer to these problems is often already sitting in the logs. The Clash core (whether the original Clash or the more commonly used Clash Meta / mihomo core) writes a line for every connection it handles: where the traffic came from, which rule it matched, where it tried to connect, whether the connection succeeded or failed, and why it failed if it did.

In other words, logs break down the vague symptom of "no connection" into concrete stages: did the local client fail to send the request, did DNS resolution fail, or was the connection rejected during the handshake by the target or the node. Once you can read logs, troubleshooting stops being guesswork and becomes evidence-based, which is much faster.

Log levels and where to find them

Clash logs come in several levels, roughly from lowest to highest: debug, info, warning, error, silent. The lower the level, the more detail is recorded:

• debug: records nearly every internal action, including each DNS query and each connection attempt. Most useful for hard problems, but produces a large volume of output.
• info: the recommended level for everyday use — records key events like connections established, rule matches, and connections closed, without flooding the screen.
• warning / error: only records abnormal connections. Quiet day to day, but gives you less to work with when troubleshooting.

Most GUI clients put the log panel in a sidebar or bottom tab on the main window, usually labeled "Logs." You can typically switch levels directly from the interface. When chasing a specific issue, switch temporarily to debug, reproduce the problem once, then switch back to info to avoid generating excess log files over time.

Common log entries explained

The exact format varies slightly by core version, but the core information is consistent: time, level, protocol type, source address, destination address, matched rule and policy, and outcome. Here's a breakdown by error type.

Connection errors: connection refused / timeout

[TCP] 192.168.1.5:51234 --> example.com:443 match RuleSet(proxy) using NodeA
dial tcp 203.0.113.10:443: connect: connection refused

connection refused means the TCP handshake was explicitly rejected by the target, usually meaning no service is listening on that port, the node's server side is down, or the node itself is having issues. i/o timeout is different — it means the request went out but received neither a rejection nor a response, which is common with congested routes, an unresponsive target server, or a node's network being throttled or blocked. The distinction matters: a refusal usually calls for switching nodes, while a timeout points first to route quality.

DNS resolution errors: no such host

dial tcp: lookup example.com: no such host

This line appears before a connection is even attempted, meaning domain resolution itself failed — the process never even got to the node connection stage. Common causes are an unreachable DNS server, a typo in the nameserver setting, or a routing rule that requires a specific DNS mode without fake-ip or enhanced-mode being enabled to match. If nearly every domain triggers this error, check the DNS configuration itself; if only a specific domain fails, it's more likely that domain genuinely resolves poorly on some DNS servers.

Rule match entries: confirming traffic routing

[TCP] 10.0.0.8:60021 --> api.example.com:443 match DomainSuffix(example.com) using DIRECT

This type of entry isn't an error — it's a "traffic routing report." What follows match is the specific rule that was hit, and what follows using is the policy actually applied (DIRECT, a specific node, or a policy group). If a site that should go through a proxy shows using DIRECT in the log, the rule either didn't take effect or is placed after a conflicting direct-connect rule. Conversely, if a site that should connect directly is instead routed through a proxy, this is where you'll spot it first. Rule-match entries are the most direct evidence for whether your configuration is behaving as expected.

TLS and handshake errors

remote error: tls: handshake failure
EOF

A handshake failure or an unexpected EOF (the remote end closing the connection) is often caused by a mismatch between the node's transport protocol settings and the server side (for example, TLS parameters or the SNI camouflage domain not matching), or by the node's server flagging the connection during traffic inspection. This is usually not a local configuration issue — try a different node first to verify. If several nodes show the same type of error, go back and review how the corresponding protocol fields are written in your local configuration.

Tracing the issue on a timeline: from request to response

Once you have a log snippet, go through it in this order rather than just scanning for anything in red:

1. Was the request captured locally at all? Confirm the connection actually shows up in the log. If there's no record at all, the problem is likely that the system proxy never took effect or TUN mode isn't intercepting traffic — not a node issue.
2. Did DNS resolution succeed? Look for a no such host style entry. If resolution fails, none of the later connection steps will happen.
3. Did rule matching go as expected? Confirm the policy pointed to by match and using is actually the one you intended. Hitting the wrong policy group is easier to overlook than hitting the wrong node.
4. Was the connection established? Look for connection refused, timeout, or TLS-related errors. This step usually tells you whether to "switch nodes" or "check the route."
5. Did the connection close normally after use? A normal request should end with a connection-closed entry. If a connection hangs for a long time with no closing entry, the target service may simply be slow to respond, rather than a network-layer issue.

Running through these five steps mentally usually turns the vague symptom of "can't connect" into a specific, pinpointed stage.

Common scenarios: quick reference table

A few tips for troubleshooting

Treat logs as a chain of evidence, not a signal light that just tells you "something's broken wherever it's red." The same error appearing across multiple nodes usually points to local configuration or DNS; an issue isolated to a single node usually reflects that node's own status. Getting into the habit of checking logs before touching the configuration saves a lot of trial-and-error time.

If the same type of error keeps showing up in your logs and you've already ruled out local configuration and network environment issues, it's worth going back through the official quick-start guide to confirm your subscription, DNS mode, and rule configuration are all at their recommended defaults.