October 2, 2026 Troubleshooting 11-minute read

How to Read Clash Logs: log-level Settings and Common Errors Explained

Learn what each log-level reports and how to interpret common Clash errors like dial tcp timeouts, i/o timeouts, and unmatched rules.

Start with the failure stage, then check the log level

Read Clash logs in this order: did the connection reach the core, which rule matched, which policy was used, and where did it fail? warning describes an event severity; it does not mean the entire client is unavailable. One i/o timeout is not enough to prove a node is down. Check the timestamp, destination, policy, and error from the same request together to decide whether to investigate the local port, DNS, or proxy server.

# Merge into the top level of the active config; do not add a duplicate field
log-level: info

This article covers common Clash configurations and the Clash Meta (mihomo) core. Log formats, field names, and localized messages vary between cores and clients. The examples below explain how fields relate; they are not guaranteed to match the exact output of every version. Before troubleshooting, note the client version, core name, and core version—not just the desktop app version.

Choosing a log-level

log-level is a top-level YAML field; it does not belong under dns or proxy-groups. Common values are silent, error, warning, info, and debug. The value is warning, not warn. WARN in a log is an output label; that does not mean the config accepts the same spelling.

Config value	What it reports	When to use it
`silent`	Suppresses routine core log output	Not suitable for diagnosing connection issues; the client may still show its own messages
`error`	Error events	Produces fewer entries and may omit useful connection warnings
`warning`	Warning and error events	Useful for connection problems, but not for tracing normal routing
`info`	Routine runtime information and more severe events	Check rule matches, policy selection, and basic connectivity
`debug`	Adds debug details	Briefly trace parsing, connections, and internal processing

Why didn't changing the setting show more logs?

Make sure you changed the active profile, not another config that has not been selected.
Check whether runtime settings or an override in the client changed log-level back to another value. The final active config is more useful than the original subscription content.
Reload the config using the client's supported method. If it supports runtime changes, adjust the setting there instead of repeatedly restarting the system.
Clear keyword and level filters in the log viewer, then make a new request. Switching to debug does not add detail to existing entries.

If the config will not load, check the startup log or the client's core output. An empty log list may mean the core has not started; there is no point investigating proxy rules yet.

Which fields to check in a connection log

Follow the connection path first, then read the error at the end. This structured example shows a local ephemeral source port, a website's HTTPS port as the destination, and Proxy as a sample policy group name.

[TCP] 127.0.0.1:53124 --> www.example.com:443
match DomainSuffix(example.com) using Proxy[Node A]

[TCP] dial Proxy (match DomainSuffix/example.com)
127.0.0.1:53124 --> www.example.com:443
error: dial tcp 192.0.2.10:443: i/o timeout

192.0.2.10 is a documentation-only example address, not a working node. The dial address in a real log might be a proxy server, a direct destination, or a resolver. The final IP alone cannot tell you that a website is down. Check the active outbound policy and full error context to determine what the core is connecting to.

Time: Does it match your manual test, or is this a connection left by an earlier background request?
Network type: TCP and UDP are not interchangeable. A working website does not mean a game or another UDP app will work.
Destination: Is it a domain or an IP, and is the port expected? HTTPS commonly uses 443.
Rule and outbound: Which rule matched, which group did the connection enter, and what did the group ultimately select: a node, DIRECT, or REJECT?
Failure stage: Did it fail during DNS resolution, TCP connection setup, the proxy handshake, or a later read/write?

What dial tcp and i/o timeout mean

dial tcp means a TCP connection is being attempted; it is not the cause of the error. The following i/o timeout, connection refused, or network is unreachable points to the failure. Proxy handshakes, TLS negotiation, and application requests happen at different stages, so a successful TCP connection alone does not prove the whole path is working.

Error snippet	What it tells you	What to check next
`dial tcp … i/o timeout`	A TCP connection to the specified address did not complete in time	Check the address and port, network path, service availability, and firewall
`i/o timeout`	A network read or write timed out; the stage is unclear from this alone	Keep the surrounding log entries and check whether a connection was established or a handshake began
`connection refused`	The connection was refused, either by the destination or by a network device	Check the listening port and service status; DNS settings should not be your first change
`network is unreachable`	The current network stack could not find a usable route	Check routing, network interfaces, and IPv4/IPv6 connectivity
`connection reset by peer`	The peer or an intermediate device reset the connection	Check the protocol, server logs, and time of the failure; this alone does not identify who is responsible
`EOF`	The connection closed while data was being read	Check the protocol parameters if this happened during a handshake; it may also be a normal closure

Separate timeouts affecting every node from timeouts affecting a single destination

If several different servers time out while dialing, check the local network, routes, firewall, and whether the subscription URL is still valid. If only one node fails, first check that node's server address, port, and service status. If that node works with other sites but only one domain fails, investigate the destination site, its DNS resolution, and the routing result. Latency tests usually contact a specific test endpoint; passing one does not guarantee access to every website.

Telling DNS, TLS, and port errors apart

DNS failures: distinguish the node's domain from the destination domain

lookup … no such host points to a DNS resolution failure; DNS … timeout means the lookup did not finish in time. First identify whether the failed domain belongs to the node server, subscription server, or website you are trying to reach. If the node's domain cannot be resolved, the proxy connection may never have started; changing website rules blindly will not help.

A system nslookup result may differ from mihomo's internal DNS result, especially with Fake-IP, DNS hijacking, or DNS-based routing enabled. Use system DNS as a comparison, but also check the active dns config. In mihomo, proxy-server-nameserver resolves proxy node domains. Check that the field is supported by your version and configured as intended; do not copy it into older cores that do not support it.

TLS errors: check certificates, system time, and protocol settings

Errors mentioning x509 often involve certificate trust, validity, or a name mismatch. Check the system date first, then verify the node's TLS setting, server name, and server requirements. tls handshake timeout means the TLS handshake did not finish in time; it does not necessarily indicate a certificate problem. If the request is still in the handshake stage, the website has not yet returned an HTTP error.

Listener failures: restore the local entry point first

bind: address already in use usually means another process is using the local listening address and port. For example, if HTTP and SOCKS are configured to share port 7890 while another client is already using it, the core may fail to start its listener. Stop the conflicting process, or change the port and update the system proxy, browser, and terminal settings to match.

# Local listener example; 7890 is an example port, not a default for every client
mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

This is only a field snippet, not a complete config with nodes or rules. Check whether the original config already has mixed-port before editing, to avoid a duplicate key. Keep allow-lan: false if only local access is needed; opening a LAN listener will not resolve a local port conflict.

Unmatched rules: check order, mode, and final policy

“Unmatched rule” is usually a troubleshooting description, not a standardized error message across versions. A connection falling through to the final rule, entering an unexpected policy, or never reaching the core may all be described this way. Rules are checked top to bottom in rules; a broad rule near the top can capture a connection before a more specific one.

# Example: domain-specific rules first, fallback rule last
# Proxy must be a policy group or proxy name already defined in the full config
mode: rule
rules:
  - DOMAIN-SUFFIX,example.com,Proxy
  - MATCH,DIRECT

Check the mode first: global uses the global policy and direct connects directly. Neither can be used to test rule order in rule mode.
Then check the destination: An app may connect directly to an IP. Whether the domain can be recovered depends on DNS mapping, sniffing, and the actual traffic; do not assume every IP connection will match a domain rule.
Check the fallback: Matching MATCH,DIRECT means the rules are working as configured, even if the result is not what you expected. Fix the specific rule above it.
Check the group's selection: A log showing that a connection entered Proxy does not guarantee it was proxied. If the group currently selects DIRECT, the connection still goes direct.
Check for updates overwriting changes: Subscription updates may replace manual edits. For rules that must persist, use the client's supported merge or override mechanism and inspect the generated config.

If there are no logs for the traffic at all, check the entry point first. The system proxy only affects apps that follow that setting; terminals, games, and browsers with their own proxy settings may take another route. TUN can capture more IP traffic, but permissions, routes, exclusions, and DNS settings still matter. Enabling TUN alone does not prove that all traffic is reaching the core. For field details, see the config field reference.

A repeatable workflow for tracing a request

A useful troubleshooting process ties each change to new evidence. The steps below use a local HTTP proxy at 127.0.0.1:7890; update the command if your config uses another port.

Note the active profile, core version, proxy mode, selected node, and local listening port. Set the log level to info.
Stop unrelated downloads and speed tests, then note the current time. Test one destination at a time so background connections do not muddy the results.
Use the explicit proxy command below so the request does not depend on system proxy settings. In Windows PowerShell, use curl.exe to avoid differences caused by the legacy alias.
Find the corresponding connection from the same time window, check the rule and outbound, then read the final error. If there is no log entry, check the listener and viewer filters first.
If the logs lack detail, switch to debug and repeat the same request. Change only one variable per test—for example, switch nodes without also changing DNS, rules, and TUN.
Once the issue is resolved, switch back to info. Record the cause and final active settings instead of leaving verbose debug output on.

curl --proxy http://127.0.0.1:7890 --connect-timeout 10 --max-time 15 --verbose https://example.com/ --output /dev/null

When using curl.exe on Windows, replace the output target /dev/null with NUL. The 10-second limit applies to curl's connection phase, while 15 seconds is the total request limit; neither changes the core's internal timeouts. The command's --verbose option shows the proxy connection and TLS process. For HTTPS through an HTTP proxy, a successful CONNECT only means the tunnel is established; check the subsequent handshake and response too.

What to keep private when sharing logs

When asking for help, include when the issue occurred, the client and core versions, relevant modes, destination port, rule result, and a continuous log covering the request. Keeping roughly 10–30 lines around the same reproduction is usually more useful than a screenshot of the final timeout alone. Preserve the hierarchy and field names in config snippets, but remove credentials that could grant access to a service.

Redact full subscription URLs and their query parameters, node passwords, UUIDs, access tokens, and the control interface's secret.
Redact real domain names, LAN addresses, and node addresses as needed, but use consistent aliases for the same items so their relationships remain clear.
Keep the error type, destination port, TCP/UDP type, and rule order; they directly affect the diagnosis.
Do not upload the full subscription file by default when asking for help. A large number of nodes cannot make up for missing reproduction steps.

A final diagnosis should identify a specific layer: the request never reached the local listener, the wrong rule was selected, dialing the node failed, the protocol handshake failed, or the destination returned an unexpected response. Classify the issue before making changes; that preserves more useful evidence than repeatedly reinstalling the client or resetting everything at once.