How to Read Clash Runtime Logs: Common Errors and a Troubleshooting Order

Identify the log source and time range first

The “logs” in a Clash client may come from two distinct layers: the graphical client handles subscription downloads, configuration switching, core startup, and system proxy settings; cores such as Clash Meta (mihomo) handle DNS, rule matching, connection establishment, policy-group selection, and TUN traffic processing. When both types of logs appear in one window, first determine which layer produced the error.

For example, a subscription request returning 403 usually belongs to the client’s configuration update flow, while a connection timing out after a domain matches a rule belongs to the core’s runtime. Capturing only the last line can confuse the result with the cause. Instead, review the entries preceding the failure time, find the first abnormal line, and identify the last normal entry immediately before it.

What a log line usually contains

• Time: Links a user action to its log entry, such as the exact moment a subscription update was clicked, a node was switched, or TUN was enabled.
• Level: debug provides detailed process information, info records normal status, warn flags something that needs attention without necessarily interrupting execution, and error means the current step failed.
• Module: Common modules include configuration loading, DNS, inbound listeners, proxy dialing, rule matching, and TUN.
• Target: This may be a domain, IP address, port, network interface, configuration file path, or policy-group name.
• Error chain: An error may contain several linked phrases. They usually describe the execution path from left to right, with the final phrase giving the direct cause returned by the operating system or network library.

Before troubleshooting, reproduce the smallest possible failure once: clear the log or note the current position, perform one action, and save that short section. If a webpage will not open, do not update the subscription, switch modes, change DNS, and replace the node at the same time. Changing several conditions at once makes the causal relationships in the log unreliable.

Startup and configuration parsing errors: inspect the file before the ports

When the core cannot start, later DNS, rule, and node tests are meaningless. First confirm that the configuration file can be read and parsed, then check listening ports, the control port, file permissions, and resource files. A graphical interface showing “startup failed” is only a summary; the actual cause is usually found in the preceding few lines.

Configuration syntax and field errors

Common messages include yaml, unmarshal, invalid config, field not found, or a specific line and column number. YAML is indentation-sensitive: tabs, incorrect nesting, unclosed quotes, and malformed lists can all prevent loading. The following rule must be placed inside a list:

rules:
  - DOMAIN-SUFFIX,example.com,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

If the log reports an unknown field, also verify the target core type and version. Some fields supported by Clash Meta (mihomo) are not available in older Clash configurations, and the reverse can also occur. Do not assume compatibility just because the file extension is .yaml; check field names, proxy protocols, rule-set syntax, and the DNS configuration structure.

The port is already in use

address already in use means that another process has already claimed the specified listening address and port. Common examples are mixed-port, port, socks-port, and external-controller. This often happens when an older core did not exit cleanly, another proxy tool is running, or two configurations are listening on the same port.

The order of operations is: check for duplicate Clash or mihomo processes, inspect other proxy software, and only then consider changing the port. After changing it, update the proxy port configured in the browser, terminal environment variables, or LAN devices. Otherwise, the core may start successfully while applications continue connecting to the old port.

Permission and file path issues

permission denied must be interpreted in the context of the target path. Failure to access the configuration directory usually points to directory permissions or a locked file; failure to create a TUN interface may involve administrator privileges, system extensions, or network-service permissions. no such file or directory often indicates that a referenced rule set, GeoIP database, or certificate file is missing. Check the complete path shown in the log rather than only the main configuration file currently open.

Subscription update errors: distinguish download failures from parsing failures

A subscription update consists of sending a request, receiving a response, identifying its contents, generating a configuration, and loading that configuration. The interface may report “update failed” for any of these stages, but each requires a different response. Record the HTTP status, response type, and parsing details first, then decide whether to investigate the network, subscription access, or format compatibility.

A subscription URL opening in a browser does not guarantee that the client can update successfully. The browser and client may use different network paths, User-Agents, DNS results, or proxy settings. During troubleshooting, rely on the status code and response recorded by the client rather than only on the browser page.

Also distinguish between an empty subscription response and a configuration with no usable nodes. Some subscriptions return a complete Clash configuration containing proxies, proxy-groups, and rules; others provide a generic node list that the client must convert. If the converter does not recognize a protocol field, it may generate only some nodes or fail to generate policy groups altogether. Preserve the information about the original response type and verify that the subscription explicitly provides Clash or Mihomo format.

DNS errors: determine whether resolution or connection failed

DNS entries often appear before connection errors, but an unreachable domain is not necessarily a DNS problem. First check whether the log obtained a target IP address: an explicit resolution timeout, unreachable upstream, or empty response indicates a DNS-stage failure; if an IP was returned and dialing or TLS then timed out, continue examining the proxy path.

Common DNS log messages

• no such host: The system resolver or specified upstream returned no usable address, or the domain name may be misspelled.
• i/o timeout: The DNS query received no response from the upstream within the deadline; check the upstream address, network path, and firewall.
• connection refused: The target DNS service is reachable, but its port is not accepting connections, or a local forwarding service is not running.
• server misbehaving: The upstream response is abnormal, possibly due to protocol incompatibility, an invalid response format, or interference in the network path.
• fake-ip-related entries: The domain has entered the Fake-IP mapping flow. This is not an error by itself; inspect subsequent rule matching and the actual connection result.

In Fake-IP mode, the application first receives a mapped IP from a reserved address range. The core then restores the domain from that mapping and applies the rules. When the target address falls within the Fake-IP range, do not treat it as the remote server’s address. If some LAN services, time synchronization, games, or special protocols misbehave, check whether the relevant domains should be excluded through fake-ip-filter; avoid adding large numbers of domains to the filter without a specific reason.

With TUN enabled, DNS may also pass through interception and redirection. The DNS server shown in system settings may therefore differ from the upstream actually used. Check Clash’s dns.enable, listening address, nameserver, fallback, or policy-based DNS settings together with TUN DNS hijacking. If port 53 is already occupied by a local resolver, the log will usually report a listening failure during startup rather than waiting until a webpage is opened.

dns:
  enable: true
  listen: 0.0.0.0:1053
  enhanced-mode: fake-ip
  nameserver:
    - 1.1.1.1
    - 8.8.8.8

The example above only illustrates the relationship between fields. Choose upstreams according to the current network and core documentation. When changing DNS, change one setting at a time and repeat the test with the same domain. Switching enhanced mode, upstream protocol, and TUN hijacking simultaneously makes the log difficult to interpret.

Connection, handshake, and timeout errors: inspect each segment of the proxy chain

Once the rules select a policy and node, the core connects to the proxy server, which then accesses the destination. A timeout in the log may occur between the local machine and node, between the node and destination, during the proxy-protocol handshake, or during the TLS handshake. The key is to identify the outbound name, destination address, and network type immediately before the error.

connection refused

A refused connection means the target host explicitly reported that the port is unavailable. If the target is a proxy node, check the node port, service status, and protocol settings; if it is the local control port, verify that the client is using the correct control address. Unlike a timeout, which usually means no response arrived in time, a refusal means the network reached a host but that port was not accepting connections.

i/o timeout and context deadline exceeded

These messages mean that an operation exceeded its time limit. Switch to a known-working node and test the same destination first. If several nodes time out, check the local network, DNS, system firewall, and proxy mode; if only one node times out, investigate that node’s route first. If ordinary websites work but a particular site times out, check whether the rules assigned the domain to an unsuitable policy.

EOF, connection resets, and TLS handshake failures

EOF means the connection closed before the expected data was complete; by itself, it does not identify the cause. The remote side may have closed it, proxy-protocol parameters may not match, transport settings may differ, or an intermediate device may have reset the connection. connection reset by peer more specifically means that the peer or a device along the path reset the connection.

For TLS errors, check the system time, certificate hostname, SNI, node transport settings, and destination site. If the log reports a certificate-name mismatch, do not mask the problem by permanently disabling certificate verification; verify the server name and node parameters instead. An inaccurate system clock can also make certificates appear not yet valid or already expired.

UDP and TCP behave differently

A node opening webpages only proves that the main TCP path works. Voice calls, games, QUIC, and some DNS requests rely on UDP. If the log shows a UDP connection failure, confirm that the node protocol and server support UDP, that the policy group selected an appropriate node, and that the system firewall permits the traffic. You can temporarily let the application fall back to TCP to determine whether the issue is limited to UDP, but the actual configuration should still be fixed.

Rule matching, proxy modes, and TUN: a normal log can still indicate the wrong path

Some failures produce no obvious error. A connection can succeed while using the wrong node or bypassing the proxy unexpectedly, which usually points to a rule, mode, or traffic-capture-scope issue. Temporarily set the log level to debug and observe the relationship between the domain, process, rule type, policy group, and final outbound. Restore the usual level after testing to prevent the log volume from growing continuously.

Confirm the current proxy mode first

• Rule mode: Rules are evaluated from top to bottom, and the specified policy is used after a match. Most fine-grained routing issues should be investigated in this mode.
• Global mode: All traffic is handed to the global policy, so the rule list usually does not participate in normal routing. It is useful for testing node connectivity, but it cannot verify that rules are correct.
• Direct mode: Traffic connects directly to the destination. If you forget to switch back to rule mode, the node may be healthy while the expected proxied connection never occurs.

In rule mode, order matters more than the number of rules. For example, a broad DOMAIN-SUFFIX rule placed before a specific rule may intercept the destination prematurely; the positions of GEOIP, GEOSITE, rule sets, and the final MATCH also change the result. If the log shows an unexpected match, search for that rule in the configuration and inspect the scope covered by the rules before it rather than changing only the final policy group.

rules:
  - DOMAIN,api.example.com,DIRECT
  - DOMAIN-SUFFIX,example.com,PROXY
  - GEOIP,CN,DIRECT
  - MATCH,PROXY

With the order above, api.example.com connects directly first, while other example.com subdomains enter the proxy. If the two rules are swapped, the specific rule will never have a chance to match.

TUN is enabled, but the application does not appear in the log

If an application’s request produces no corresponding connection entry at all, the problem is usually before traffic reaches the core. Check that the TUN interface was created successfully, the default route was installed, automatic routing is working, and other VPNs, virtual adapters, or security software have not changed route priority. Some applications also use independent proxy settings; if those point to an old port, they can bypass the current TUN path.

When the log shows operation not permitted, interface creation failure, or route-addition failure, check runtime permissions and the system’s networking capabilities. On Linux, also inspect the TUN device, network manager, routing table, and service-account permissions; on Windows and macOS, check the virtual adapter, system extension, or administrator authorization status. Client packaging differs, so base the diagnosis on the actual system operation that failed in the log.

A reusable troubleshooting order: from the first anomaly to the configuration field

A reliable troubleshooting process moves gradually from lower-level state to the specific request. Changing nodes before checking startup status, or rewriting the entire DNS configuration at the sight of the word DNS, usually adds variables. The sequence below applies to common cases such as failure to start, subscription update failures, webpages not opening, and problems affecting only some applications.

1. Define the failure boundary. Determine whether it affects every website, one domain, a particular application, TCP, UDP, or only occurs when TUN is enabled.
2. Confirm that the core is running. Check that the configuration loaded successfully, the proxy and control ports are listening, and there are no permission or missing-file errors.
3. Confirm the configuration source. If you just updated a subscription, first verify that the download succeeded, the response used the correct format, and the new configuration can be parsed.
4. Confirm that the request reaches the core. Run one reproducible test and check for a connection entry at the corresponding time. If none appears, inspect the system proxy, application proxy, and TUN routes.
5. Confirm the DNS result. Check whether the domain resolved, whether the Fake-IP mapping matches the current mode, and whether the DNS upstream timed out.
6. Confirm the rule and policy. Check the current mode, matched rule, policy group, and actual node so that incorrect routing is not mistaken for a node failure.
7. Confirm the connection stage. Distinguish the local-to-node path, protocol handshake, TLS, node-to-destination path, and UDP path, changing only one test condition at each stage.
8. Roll back the latest change. Restore the last working configuration, then apply DNS, TUN, rule, or node changes one at a time to identify the smallest difference that introduced the failure.

A useful troubleshooting record should include at least the client and core names, operating system, failure time, current mode, whether TUN is enabled, reproduction steps, the first abnormal log entry, the matched policy, and the individual variables already tested. Version numbers also matter because supported fields, default behavior, and error messages change as the core and client are updated.

The goal of log analysis is not to collect as many error lines as possible, but to reconstruct the execution order: the configuration is read, ports begin listening, the subscription produces a configuration, DNS provides a destination, rules select a policy, the node establishes a connection, and TUN determines whether more application traffic enters the core. Place each log entry back on this chain to narrow the vague claim that “Clash does not work” down to a specific field, port, upstream, or network interface.