How to Read Clash Logs: Common Errors and Step-by-Step Troubleshooting

Confirm the Log Source and When the Failure Occurred

Clash logs are more than a list of errors. They record configuration loading, listening ports, DNS requests, rule matching, and outbound connections. Start troubleshooting by answering three questions: Did the request reach the core? Which policy did it take? Where did the connection fail? Replacing every proxy node after seeing one red error can blur the distinction between a port issue, a DNS problem, and a remote service outage.

This guide applies to clients running the Clash or Clash Meta (now called mihomo) core. Log formats and menu names can vary by client and core version. First note both versions on the client's About page, then open Logs or Runtime Logs. Don't confuse subscription update logs or client UI logs with core runtime logs.

1. Note the local time of the failure to the nearest second, for example 14:32:10.
2. Pause downloads, video, and other ongoing network activity, clear the log history in the interface, then trigger the request you're investigating just once.
3. Keep about 10 seconds of logs before and after the request. On the Connections page, check the target domain, destination port, matched rule, and actual outbound route.
4. Note whether the current mode is Rule, Global, or Direct, and whether System Proxy or TUN is enabled. Change just one setting per test.

Adjusting log-level: Start with info, then use debug briefly

Use info for routine troubleshooting. It usually shows the connection target, matched rule, and selected policy. Switch to debug temporarily only when DNS resolution, policy providers, or connection details are unclear. silent disables logging, so it isn't useful for troubleshooting. error and warning may omit successful connections and rule details.

Check the Configuration and Confirm It Took Effect

Look for a Log Level setting in the client. If there isn't one, use the client's supported configuration editor or override mechanism to change the top-level field. The values below are core configuration values: use warning for the warning level; don't infer the configuration value from an abbreviated UI label.

# Top-level configuration; restore info when troubleshooting is complete
log-level: debug
mode: rule

• After saving, reload the configuration using the client's built-in option. If prompted to restart the core, follow the instructions and confirm it starts without errors.
• Remote subscriptions may overwrite direct edits when they update, so use a persistent override method supported by the client whenever possible.
• Reproduce the issue once and export only the relevant time window; there's no need to leave debug running for hours. Restore info when you're done.

Debug logs may contain visited domains, local addresses, node names, and configuration paths. Before sharing them, remove subscription tokens, credentials, control API secrets, and personal directory details. Keep the error type, ports, and policy relationships so the logs remain useful for troubleshooting.

Trace a Connection: Target, Rule, and Outbound Route

Search for the target domain or port instead of guessing from the first line of a full-screen log. A single page load may request the main site, images, APIs, and analytics domains; one failed entry doesn't necessarily mean the main page connection failed. Here's a simplified TCP connection example:

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

If you see using DIRECT, first check whether that route is expected instead of immediately assuming the rule failed. A connection entry shows the routing decision, not whether the remote request succeeded. Check subsequent errors, connection traffic, and the application's result too.

dial tcp timeout: Find Out Which Connection Timed Out

Search for dial tcp, i/o timeout, or context deadline exceeded to find connection or operation timeouts. dial tcp points to the TCP connection setup stage, but other timeout messages can arise during DNS queries, TLS handshakes, or proxy protocol negotiation. Read the destination address and operation description around the error.

First, Distinguish the Node Address from the Website Address

• Timeout connecting to the proxy node: The error address belongs to the node server and port. Check that the node's domain resolves, the port is correct, the server is reachable, and the subscription is current. Then try another available node in the same policy group.
• Timeout connecting directly to a website: The connection entry shows DIRECT and the target is the website. Check the direct network connection, target service, and rule selection rather than changing node settings.
• Website request fails through a node: The node connection succeeds, but the request to the target fails. Compare the same node against other websites, and other nodes against the same website, to narrow it down to the target or the node's exit route.

connection refused is different from a timeout: the connection was actively rejected, often because nothing is listening on the target port, though an intermediary may also reject it. connection reset by peer means the connection was reset. Neither message alone proves an incorrect password or a specific type of network interference.

DNS Resolution Failures: Check Both Resolution Paths

At minimum, distinguish a failure to resolve the proxy node's domain from a failure to resolve the target domain. The former stops the proxy connection before it can be established; the latter depends on the current DNS mode, target resolution path, and upstream resolver. Read messages such as lookup, no such host, DNS resolve failed, and query timeouts alongside the domain that follows them.

1. Check the spelling and purpose of the domain. If the failed domain belongs to a node server, first check the node configuration and make sure the domain is still valid.
2. Distinguish a DNS response from a timeout. no such host commonly means the domain doesn't exist or has no usable records. For query timeouts, check whether the upstream DNS server is reachable, along with its transport and route.
3. Check resolver bootstrap dependencies. When using a DoH upstream specified by domain name, the resolver's own domain must be resolved first. mihomo fields such as default-nameserver and proxy-server-nameserver serve different purposes. Check the documentation for your version; don't swap their addresses arbitrarily.
4. Reload, then make a new connection. After changing DNS settings, clear the cache or restart the core using a method supported by the client, and close the application's existing connections so old results don't affect the diagnosis.

A Fake-IP Address Doesn't Mean DNS Is Broken

With Fake-IP enabled, the client may return a virtual address from its configured address pool, often in the 198.18.0.0/16 range. This maps later connections back to the domain; it isn't the website's public IP address. Seeing one doesn't by itself mean DNS is being tampered with. Check whether the core is handling the connection and whether the domain mapping is still valid.

Results from nslookup in a system terminal may not match what the core actually uses. System DNS, browser Secure DNS, core DNS, and resolution through a remote proxy can all take different paths. When troubleshooting TUN, also confirm that DNS hijacking and routing are actually working, rather than just checking for enable: true in the configuration.

Rules Not Matching: Check the Mode and First Matching Rule

In Rule mode, rules are evaluated in order, and usually the first match determines the outbound route. Global mode doesn't select a policy for each connection using the usual rule list; Direct mode connects directly. So if a domain rule seems to send traffic to the wrong node, first check that the client is actually in rule mode.

# Example: Proxy must be the name of a policy that already exists in the configuration
rules:
  - DOMAIN-SUFFIX,example.com,Proxy
  - MATCH,DIRECT

In this example, example.com and its subdomains should match the first rule; connections that don't match it fall through to MATCH,DIRECT. If a broader rule comes first, later, more specific rules may never be reached. Check the rules currently active in the client, not just the subscription source file.

• Logs show only an IP address: Check whether the application bypassed core DNS resolution and whether the connection retained domain information. A domain rule can't identify a site from a bare IP address alone.
• A fallback rule matched: Check whether the target is actually an API or CDN subdomain, and whether the rule provider loaded successfully or reported update errors.
• The rule is correct, but the node is wrong: Check the policy group's current selection. An auto-test or failover group may select members according to its own logic.
• Traffic still uses the old policy after a change: Close the relevant existing connection and try again. Long-lived connections may not be rerouted as soon as the rules reload.

mihomo's domain sniffing can supply domain information for supported protocols under the right settings, but it can't recover a domain from every encrypted connection. Don't treat sniffing as a universal fix for rule issues, or leave all traffic in Global mode just to fix one website.

No Connection Entry in the Logs: Check the Listener and Traffic Capture

If the application reports an error but there's no corresponding core log entry, first check whether the request reached the client. System Proxy affects only applications that honor the system proxy settings. Some command-line tools, games, and apps with their own proxy settings need separate configuration or suitable TUN capture. Enabling System Proxy doesn't mean all TCP and UDP traffic is routed through the core.

Test Once Through an Explicit Proxy Listener

Suppose the mixed port in the active local configuration is 7890. You can use the explicit proxy request below to test it. This is only an example: replace it with the listening port currently shown by the client. Don't copy it if the port is 0 or the listener is disabled.

curl -v --proxy http://127.0.0.1:7890 --connect-timeout 10 --max-time 20 https://example.com/

In Windows PowerShell, replace the start of the command with curl.exe to avoid command alias differences in some environments. Watch the logs as you run it: if the request reaches the core but the browser's doesn't, check the browser's proxy settings, extensions, and connection reuse first. If you immediately get a connection error for 127.0.0.1:7890, check that the core is running, the port is correct, and the listener started successfully.

• address already in use: The listening address or port is already in use. Check whether two proxy clients are running at once. Stop the conflicting service or change the listening port, then update the proxy entry settings to match.
• permission denied / operation not permitted: Check the surrounding log entries for TUN, routing, or file access permissions, then grant the required permissions as prompted by the client.
• authentication failed: Determine whether the error concerns local listener authentication, proxy node authentication, or subscription download authentication. Don't mix up credentials for these three.
• TUN won't start: Check the first error when creating the virtual network adapter, adding routes, or checking permissions. Don't keep testing blindly while another VPN is also modifying routes.

This curl test mainly checks the explicit HTTP proxy listener and its request path. It doesn't prove that TUN, UDP, or every application is working. If the client has settings such as automatic TUN routing, interpret the result alongside the actual routes.

Reproducible Test Steps and Troubleshooting Notes

A useful bug report lets another maintainer repeat the same steps; a screenshot showing dozens of red log lines isn't enough. Follow the sequence below, confirming each stage before moving to the next.

1. Core startup: Confirm the configuration loaded, required ports are listening, and the core isn't restarting repeatedly.
2. Request reaches the core: Use an explicit proxy test or the application's connection entry to confirm the core can see the target request.
3. Resolution succeeds: Distinguish the node domain from the target domain and confirm the failure isn't in an earlier DNS step.
4. Routing is as expected: Record the matched rule, policy group, and final node. Close existing connections and retest if needed.
5. Compare outbound paths: Try another node for the same target, then another target through the same node. Change only one condition at a time.
6. Restore settings: Change debug back to info, remove temporary rules used only for diagnosis, and confirm that commonly used apps can connect.

Include This Information When Reporting an Issue

Include your OS version, full client and core versions, proxy listener and port, outbound mode, TUN status, time of failure, and relevant logs with sensitive details removed. “A browser request to a domain fails, but curl through the explicit proxy succeeds” is more useful than “the network suddenly stopped working.” “Only one node fails; another in the same group works” narrows it down further to the node configuration or network path.

If the logs show that a connection was established but the application still reports a certificate, login, or HTTP status error, continue troubleshooting at the application layer. An incorrect system clock, an HTTP 403 response, account status, and certificate trust can't be fixed by changing rule order. The goal is to identify which layer is failing and verify the fix with the same request—not to make the log view look free of warnings.