Reading Clash Logs: Common Error Meanings and How to Diagnose Them

Why check logs before switching nodes

When a page won't load or a connection lags, most people's first instinct is to switch subscriptions or try a different node, and if a few attempts fail, suspect the client itself is broken. This path is inefficient, because the proxy chain involves local configuration, node availability, cross-border route quality, and target site responsiveness — blindly swapping nodes only rules out a small slice of these possibilities. A faster approach is to open the logs page and see exactly what the client recorded while handling that connection request — the error text usually points straight to which layer the problem is in.

Logs in Clash-family clients are essentially real-time output from the core (Clash Meta / mihomo) at runtime; the client UI just renders that text with coloring and filtering. Understanding the log structure and the meaning of common fields is the most basic and effective skill for diagnosing connection issues.

Log levels and field structure

Open the client's logs page (usually labeled Logs in the sidebar) and you'll see a line like this:

[Info] [TCP] 192.168.1.5:51234 --> example.com:443 match Rule(DOMAIN-SUFFIX,example.com) using Proxy-HK

This line contains four key parts:

• Log level: Info, Warning, Error, etc. in brackets, indicating severity.
• Protocol and connection direction: TCP or UDP, plus the local port pointing to a target domain/port.
• Matched rule: which routing rule in the config file this connection hit.
• Proxy node used: the node or policy group name that actually forwarded this connection.

Log levels typically fall into four tiers, and the minimum displayed level can usually be adjusted in the client's settings:

1. Debug: the most detailed, including the full rule-matching process; not needed day to day, only when digging into tricky issues.
2. Info: the default level, recording normal connection establishment, rule matches, node switches, and the like.
3. Warning: non-fatal anomalies, such as a DNS query falling back to a secondary resolver, or a node probe timing out while alternatives remain.
4. Error: connection failures, config load errors, and similar issues that need attention, usually with specific error text.

When troubleshooting, set the level to Info or Debug first, reproduce the problem once (say, opening a page that won't load), then look back at the Error and Warning entries to pin down exactly which request failed.

Connection refused errors

This is one of the most common errors, with full text usually looking like:

[Error] [TCP] dial tcp 203.0.113.10:443: connect: connection refused

It means the local end sent out the connection request, but the other side (which could be the node server or the target site) actively refused this TCP connection. There are three common causes:

• The node server is unavailable: the node is offline, the port was temporarily closed by the provider, or the node itself is misconfigured (port number or encryption method doesn't match the server side). Switching to another node in the same subscription usually confirms this right away.
• Local firewall or security software is blocking it: some security software blocks outbound connections created by the client, especially once TUN mode is enabled. Temporarily disabling real-time protection lets you test for comparison.
• The target site rejects the current node's IP: a small number of sites restrict access from specific IP ranges — in this case the error persists on that site even though the node works fine elsewhere, and switching nodes is the only fix.

A simple way to tell these apart: try the same node against several different sites. If every site returns connection refused, it's most likely a node or local environment issue. If only a few sites fail while others work fine, it's more likely that the target site is restricting that node's IP.

DNS timeouts and resolution failures

DNS-related errors usually carry clear keywords, for example:

[Warning] [DNS] resolve example.com failed: context deadline exceeded
[Error] [DNS] all DNS servers failed to resolve example.com

The first means a single DNS lookup timed out (exceeded the configured timeout). If it's occasional, it usually doesn't affect usage — the core will retry automatically or fall back to the next DNS server. The second means every DNS server listed in the config failed to resolve the domain, in which case the page simply won't load.

Common directions to investigate for DNS resolution failures:

1. Check the DNS section of the config file: confirm the addresses in the nameserver list are actually reachable. If you're using DNS servers outside mainland China (like 8.8.8.8 or 1.1.1.1), make sure queries to those addresses are themselves routed through the proxy — otherwise they'll time out the same way direct connections would in a network that blocks them.
2. Check whether Fake-IP mode is enabled: Fake-IP assigns a domain a virtual IP, and the core performs the real resolution when the connection is actually established. If this layer is misconfigured (say, the fake-ip-range conflicts with the local subnet), a domain can appear "resolved" while the connection still fails.
3. Rule out interference from the local Hosts file or other proxy software: if another networking tool is running at the same time, or the Hosts file has stale domain mappings, the DNS layer can produce unexpected results too.

Subscription parse failures

If you see errors like the following when updating a subscription, the problem is happening at the fetch/parse step, unrelated to the proxy nodes themselves:

[Error] update subscription failed: Get "https://sub.example.com/link": context deadline exceeded
[Error] parse config failed: yaml: line 42: did not find expected key

The first is a network-level failure: the client couldn't fetch content from the subscription provider's server within the timeout. Common causes include having no usable proxy available at that moment to reach the subscription link, the provider's server being temporarily unreachable, or the subscription link itself having expired. The second is a content-level failure: the subscription content downloaded successfully, but YAML parsing failed, usually because the provider temporarily returned an error page (like maintenance-notice HTML) instead of a normal config.

To resolve subscription parse failures, check in this order:

• First confirm the subscription link opens normally in a browser and shows text content. If it opens an error page or a blank page, the problem is on the provider's side — contact the provider or wait for it to recover.
• Check the network environment used when updating the subscription: some clients route subscription updates through a "direct" connection rather than the currently active proxy. If direct access can't reach the subscription domain, the update will naturally time out.
• Check whether the subscription link contains special characters or got truncated — an extra space or a missing character when copying and pasting will invalidate the link.

Policy group health checks and node-switching logs

If the config uses policy groups with automatic health checks (types like url-test or fallback), the logs will keep showing entries like:

[Info] Proxy-HK check health: 156ms
[Warning] Proxy-SG check health failed: dial tcp: i/o timeout

These come from the core's health-check mechanism, which periodically sends a probe to each node in a policy group and records the latency or flags it as unavailable. If a node keeps showing check health failed, it genuinely has a problem right now, and the group will automatically skip it in favor of a lower-latency alternative — which is also why speed sometimes fluctuates even when nothing in the config has changed: the group is dynamically switching nodes behind the scenes.

If an entire group fails health checks, it usually points to one of two things: either the subscription itself is low quality with a large batch of unavailable nodes, or the local network environment is malfunctioning so that no outbound connection can be established at all. In the latter case, rule out local network issues first before rushing to switch subscriptions.

TUN mode errors

After enabling TUN mode (system-wide proxy that takes over all traffic), if it fails to start, the log usually gives a fairly direct hint:

[Error] start TUN device failed: operation not permitted
[Error] start TUN device failed: address already in use

The first is almost certainly a permissions issue: TUN mode needs to create a virtual network adapter, which requires the client to run with administrator privileges. If it was previously launched with normal privileges, relaunching as administrator usually fixes it. The second means the address range used by the virtual adapter conflicts with the machine's existing network configuration, which commonly happens when another virtual-adapter-based tool (like certain VPN clients) is running at the same time — close the conflicting software first, or adjust the address range TUN uses in the config.

A practical workflow for diagnosing by error type

Stringing the above categories together gives a fairly general diagnostic order:

1. Identify which layer the problem is at first: is nothing reaching the internet at all (likely a TUN or system proxy setup issue), is one specific site unreachable (more likely a node or rule issue), or is everything slow (more likely a node quality or cross-border route issue)?
2. Open the logs page and reproduce the issue once: set the log level to Info, trigger the failing access again, and note the resulting error text.
3. Categorize by keyword: dial tcp/connection refused points to a node or target-site connection issue; DNS-related entries point to the resolution layer; update subscription/parse config points to subscription fetch/format issues; TUN-related entries point to system-proxy permission or network device conflicts.
4. Rule out layer by layer: eliminate the local environment first (permissions, firewall, conflicts with other proxy software), then the subscription and nodes themselves, and only then consider site-specific restrictions from the target.

Sticking to this order usually pins down the general direction of most errors within minutes, without repeatedly trial-and-erroring through config or node changes.

Summary

Logs aren't opaque output meant for developers — they're the client actively telling you exactly where a connection got stuck. Spending a few minutes learning the keywords behind common errors and their meanings, then checking the logs before touching settings, usually saves far more time than repeatedly restarting the client or blindly switching nodes, and makes it much easier to find the real root cause.