Clash Log Guide: Common Errors and How to Troubleshoot

First, identify the log source and request time

Clash logs show how the core handles connections; they are not a complete diagnostic report for your browser. A page may fail because the app is not using the proxy, a rule selected the wrong route, DNS resolution failed, the node could not connect, or the remote service did not respond. Pinpoint the failing layer before changing settings. That is more effective than reinstalling the client whenever a red error appears.

Clash is a common name for the core and related clients; Clash Meta continued development under the name mihomo. Log fields and menu names vary across core, desktop client, and UI versions. The log lines in this article are structural examples, not results from a live network test. Do not use example ports in place of your local settings.

1. Open “Logs” in the client sidebar. If your client has no log view, look for the log directory or core log entry under “Settings.”
2. Note the current time, configuration name, operating mode, active node in the policy group, and whether System Proxy and TUN are enabled.
3. Clear the old logs, then open just one page that is failing. Wait about 10 seconds, then pause scrolling or export that short section.
4. Filter by destination domain, destination port, and time. Auto-updates, connectivity tests, and browser requests can all appear in the same window, so don’t focus only on the last error.

Setting the log level: start with info, switch briefly to debug

Common log levels are silent, error, warning, info, and debug. Use info for routine troubleshooting; it usually shows connections and rule matches. Enable debug briefly only when you need to inspect DNS resolution, dialing, or core internals.

Where to change the setting and config overrides

If the UI offers “Settings” → “Log Level,” change it there first. When managing the core config directly, set this field at the top level of the active YAML file; it is not nested under dns or tun.

log-level: info

After saving, reload the config using the method supported by your client, then check the logs again. Some clients control the log level through overrides, config merges, or runtime parameters; subscription updates may also overwrite edited files. Don’t assume a change took effect based only on the file on disk—check the UI and actual log output too. When you’re done, restore info to avoid accumulating excessive request logs.

How to read a connection log: destination, rule, route, and error chain

Use a consistent reading order: check the timestamp, then the request destination, the rule and actual route, and finally the error chain. The simplified example below illustrates the structure; real logs may use different field orders or line breaks.

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

• 127.0.0.1:53124 is the connection source seen by the core. Port 53124 is a temporary source port, not the listening port to enter in your system proxy settings.
• www.example.com:443 is the request destination. Port 443 is commonly used for HTTPS, but the port alone says nothing about whether the site’s certificate is valid.
• The text after match identifies the rule that matched. In Rule mode, rules are generally evaluated in order, so an earlier match can determine what happens next.
• using Proxy[Node A] identifies the policy and node used for this request. A policy group name is not a node server address; check which member is actually selected.
• The address after dial tcp is the destination of the connection attempt. It may be the website when connecting directly or the node address when using a proxy. Read the full error chain to tell which.

The 192.0.2.10 address in this example is documentation-only and must not be added to your config. If you see DIRECT when you expected traffic to go through a node, check the rules and mode first. If you see REJECT, look for a blocking rule; it doesn’t mean the node is offline.

dial timeout and i/o timeout: which part of the connection timed out?

dial timeout and connect: connection timed out usually mean a connection could not be established before the deadline. i/o timeout is broader and can also occur during reads or writes after the connection is established. These errors indicate that an operation timed out; they don’t necessarily mean the node is down or DNS is being poisoned.

Narrow down the issue by its scope

1. Only one site fails: Open another known-working site through the same node. Check whether the failing domain matches a different rule or is going direct.
2. Several sites fail on the same node: Switch to another node in the same policy group and repeat the same request. If only the original node fails, check its address, port, and service status.
3. All nodes fail: Confirm your local network is working, then check node hostname resolution, firewall settings, upstream network restrictions, and whether your subscription has expired.
4. Only TUN mode fails: Keep the same config and node, but test with System Proxy instead. If the explicit proxy works but TUN does not, check routing, DNS interception, and conflicts with other VPNs.

On Windows, run Test-NetConnection -ComputerName node.example.com -Port 443 in PowerShell, replacing both example values with the actual hostname and port from your config. This TCP test applies only to endpoints that use TCP; it cannot confirm that a UDP-based protocol is working. An open port also doesn’t guarantee that authentication, TLS, or the application request will succeed.

Don’t start by increasing the timeout. Waiting longer won’t fix an incorrect address, an unavailable service, or a broken network route. First identify the endpoint that timed out in the log, then decide whether a timeout setting needs to change.

connection refused: distinguish the local port from the remote port

connection refused means the connection attempt was rejected. Common causes include no service listening at that address and port, or a network device actively rejecting the connection. Unlike a timeout, this isn’t a silent wait. First check whether the refusal is from 127.0.0.1 or the node server’s address.

Connection refused at local 127.0.0.1:7890

7890 is a commonly used example proxy port, not a fixed port for every client. If an app gets a refusal when connecting to local port 7890, open the port or mixed-port settings under “Settings” in the client. Check that the core is running and that its actual listening port hasn’t changed. Also check whether the core log shows a port binding error first.

# Windows: check whether local port 7890 is listening
netstat -ano | findstr ":7890"

# macOS / Linux: find the process listening on TCP port 7890
lsof -nP -iTCP:7890 -sTCP:LISTEN

In Windows output, check both the local address column and the LISTENING state. Seeing “7890” alone doesn’t prove the proxy is running. If you find a process using the port, verify what it is before taking action; don’t terminate an unfamiliar system process.

Remote node port refused

If the refusal comes from the node address, check that the server address and port in your subscription are still valid, then refresh the subscription and try again. Incorrect HTTP proxy credentials typically produce responses such as 407 Proxy Authentication Required; not every refusal is a password problem. Even if the node port is reachable, the protocol and authentication still need to be checked separately.

DNS resolution failures: distinguish the destination hostname from the node hostname

no such host, lookup ... failed, and DNS resolve failed all point to a resolution issue, but the hostname could belong to the site you’re visiting or to the node server. If the node hostname can’t be resolved, you can’t connect to the node—even if the website’s DNS settings are correct.

• Destination site fails to resolve: Check the dns section of the active config, resolver reachability, and the resolution policies used for direct and proxied traffic.
• Node hostname fails to resolve: In mihomo, check whether proxy-server-nameserver is configured and whether its resolver can be used before the node connects.
• Can’t connect to the DoH resolver: Check the DoH URL, bootstrap resolution for its hostname, and the outbound route. Avoid a loop where connecting to the node depends on DNS, while DNS depends on a node that hasn’t connected yet.
• Fails only in TUN mode: Check TUN DNS interception settings, the system’s current DNS configuration, and whether another VPN is also changing network settings.

A successful system DNS lookup doesn’t prove the core’s DNS is working

Run nslookup www.example.com to check the response from the system’s resolver, but note that it may not use mihomo’s built-in DNS. Your browser may also have Secure DNS enabled and use a different resolution path. A result from nslookup is useful for comparison, but it doesn’t prove the resolver used by the core is working.

In fake-ip mode, synthetic addresses from the configured Fake IP range can be expected—for example, the commonly used 198.18.0.0/16. Don’t assume the connection is being hijacked just because you see one of these addresses. Check that the connection returns to the correct core route, then investigate whether upstream DNS resolution or the node connection failed. For a fuller walkthrough, see DNS troubleshooting in the manual.

Certificate, port binding, and TUN permission errors

First identify what a TLS error is connecting to. A certificate error reported by the core may occur during a node handshake, subscription download, or DNS over HTTPS request—not necessarily when a browser connects to a website. With a standard proxy, the browser usually performs the final verification of the website’s certificate when forwarding HTTPS traffic.

If creating a TUN interface or adding routes fails due to permissions, open the client’s “Settings” and look for service mode, permissions, or TUN options. Install the service or grant permissions as required by that client. Windows desktop clients may rely on an installed background service; on Linux, TUN device access and network management permissions are often involved. The exact steps vary by client. Running everything as an administrator indefinitely is not a good fix for every error.

If you change the listening port, also update System Proxy, terminal proxy environment variables, and any manual settings in browser extensions. If the core starts successfully but an app still points to the old port, local connection failures will continue.

A consistent retest sequence and log redaction

Change only one variable at a time, and retest the same domain using the same access method. If you update the subscription, switch nodes, change DNS, and enable TUN all at once, you won’t know what actually fixed the issue—even if access is restored.

1. Back up the original config and note when the issue occurred and the exact error line.
2. Confirm the request reaches the core, then check whether the expected route was selected by the rule.
3. Use the log to check DNS resolution, dialing, authentication, or TLS as appropriate; don’t guess across layers.
4. After changing one setting, reload and check the new log for the same request to see whether the error disappeared or changed.
5. Restore the normal log level, then test your browser and commonly used terminal apps so you don’t fix only one proxy route.

When reporting an issue to the maintainers, include the client name, actual client and core versions, operating system, operating mode, whether TUN is enabled, reproduction steps, and about 20 relevant log lines from before and after the error. Find the versions under “About” or in the core startup logs; don’t confuse the client version with the core version.

Before sharing, remove subscription links, access tokens, proxy passwords, control API keys, and any domains or IP addresses that could reveal personal information. Keep the field structure, ports, error types, and rule relationships intact after redaction so the issue can still be diagnosed. Don’t publish your entire subscription file, and don’t hide the underlying problem by disabling certificate verification or leaving the firewall off.