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

LOG LAYERS

Identify which layer produced the log

When the Clash client shows “connection failed,” the interface usually displays only the final result; the runtime log records which stage actually failed. Before analyzing anything, distinguish among three layers: the client interface, the proxy core, and the operating system network stack. The client manages configuration, the tray menu, and the system proxy toggle. Clash, Clash Meta, or the mihomo core in use listens on ports, parses rules, establishes proxy connections, and handles DNS. The operating system manages network adapters, routes, firewalls, permissions, and local ports. A failure at any of these layers can appear in the interface as “unable to connect.”

Different clients may display the same core log in different ways. Some preserve timestamps, log levels, and module names, while others show only the message body. Field names and wording may also change after a mihomo update. Do not search only for the entire error sentence; extract stable objects such as the configuration path, listen address, port number, domain, node name, network type, and system error.

A warning or error by itself does not necessarily mean that all proxy traffic has stopped. A timeout from one node may affect only that connection attempt or policy group; a failed backup DNS server may be bypassed by another server. To determine the scope, check the error object, its frequency, and whether successful entries appear afterward.

REPRODUCE FIRST

Reproduce the issue in chronological order

Useful log analysis requires a clearly defined reproduction sequence. Do not let the client run for hours and then guess from records mixed with configuration updates, latency tests, and background application traffic. A more reliable method is to clear the current log or note the start time, then perform only one action that triggers the issue. This makes it possible to match the user action with the log timestamps.

1. Record the current environment. Confirm the client name, core type, operating system, active configuration file, proxy mode, and whether TUN is enabled. If the client or core was just updated, record the state before and after the update.
2. Stop unrelated tests. Temporarily disable automatic latency tests, automatic configuration updates, and programs that continually create connections to reduce log noise.
3. Start with a lower log volume. Reproduce the issue at the info level first; if you can see only the connection failure result, temporarily switch to debug. Restore your usual level after locating the issue to prevent rapid log growth.
4. Perform one action only. For example, update a subscription once, open one known webpage, switch nodes once, or enable TUN by itself.
5. Locate the first anomaly. Starting at the time of the action, read downward until you find the earliest warning, error, or obvious timeout, then inspect the configuration and routing information immediately before it.
6. Change one variable and retry. Change only one of the node, port, DNS, or operating mode per attempt; otherwise you cannot tell which change made a difference.

The order of events in the log is more valuable than the number of errors. If configuration parsing fails first, a control-port connection fails next, and the interface finally reports that the core is not running, the root cause is usually the first configuration error, not the final control-port error. Likewise, if TUN initialization fails but applications can still reach the network through the system proxy, the proxy core may be working normally while the transparent interception path is unavailable.

Start the client
→ Read the configuration
→ Initialize DNS and rules
→ Listen on the local proxy port
→ Initialize TUN (if enabled)
→ Receive application connections
→ Match rules
→ Select a node
→ Establish the remote connection

Treat this chain as the diagnostic order. When an error occurs, address that step and its prerequisites first instead of immediately switching nodes or reinstalling the client.

CONFIG PARSER

Configuration parsing and core startup errors

Configuration errors usually occur before the core begins listening on its ports. Common keywords include parse, yaml, unmarshal, invalid config, field, duplicate, and not found. When these errors appear, testing nodes or the system proxy is pointless because the core may not have loaded a runnable configuration.

Unable to parse the YAML structure

YAML uses indentation to express hierarchy. Tabs, inconsistent list indentation, a missing space after a colon, or an unclosed quote can stop parsing. The log usually reports a line and column, but the actual problem may be on an earlier line—for example, an unterminated string that the parser does not recognize as invalid until it reaches the next line.

proxies:
  - name: Example
    type: ss
    server: example.test
    port: 443

proxy-groups:
  - name: SELECT
    type: select
    proxies:
      - Example

When checking the file, first confirm that indentation uses spaces throughout, then inspect several lines before and after the reported location. If a node name contains a colon, hash, or another character with YAML meaning, it must be quoted correctly by the configuration provider. If the error appeared after manual edits, revert those changes first and verify that the original configuration loads.

Field exists but is unsupported by the current core

Clash configurations are not fully interchangeable across all core versions. Some fields are supported only by mihomo; older cores may report an unknown field, a type error, or a missing required parameter. Conversely, outdated fields may trigger warnings after a client updates its core. Confirm which core the client actually invokes rather than relying only on the product name. If the configuration targets mihomo, use a client and core version that support its syntax.

Referenced object does not exist

A policy group may reference a node that does not exist, a rule may point to an undefined policy group, or a rule-set path may be unreadable. Compare the object name in the error carefully, including capitalization, spaces, and full-width characters. Names must match exactly; even seemingly identical leading or trailing spaces can break a reference.

LISTENER STATUS

Port conflicts and system proxy errors

Typical port-error keywords include address already in use, bind, listen, permission denied, and connection refused. A Clash core usually listens on an HTTP port, SOCKS port, mixed port, or external control port. If another core instance, an old client process, or another network tool already occupies the same address, the new process cannot finish listening.

address already in use means that the specified address and port are already occupied by another process. Exit all similar clients first, then check Task Manager or the system process list for a remaining core process. Do not just close the window, because some clients continue running in the tray. Once no leftover process remains, restart the client. If the port is still occupied, change it to an unused port and update the browser or application settings that depend on it.

Interpret permission denied together with the listen location. Ordinary high-numbered local ports usually require no special privileges, but security policies, firewall rules, or a restricted working directory may still block the operation. If the log mentions TUN, routes, or service registration, this is a system-permission issue—not something to fix by repeatedly changing proxy nodes.

The direction indicated by connection refused also matters. If the client interface is refused when connecting to the external control port, the core may not have started, the control address may not match, or the core may have exited. If the proxy core is refused by a remote server, the destination is reachable but its port is not accepting connections. The wording is identical, but the failure locations are completely different; check the source address, destination address, and module name in the log.

A system proxy startup failure does not mean that the core's proxy port is not working. First confirm in the log that the local proxy is listening successfully, then check whether the operating system proxy points to the correct port. If a browser configured manually can connect but ordinary applications cannot, the issue is more likely the system proxy settings, whether the applications honor them, or the applications' own network configuration.

DNS PIPELINE

DNS queries and resolution failures

DNS problems often appear as a browser reporting that a domain cannot be found, some sites working while others fail, all domain connections timing out after TUN is enabled, or repeated log entries containing lookup, resolve, no such host, timeout, or SERVFAIL. First distinguish between “the domain returned no address” and “an address was returned but the next connection failed.” If the log already shows a destination IP and has entered the dialing stage, the root cause is usually no longer the initial domain resolution.

Traditional DNS, DNS over HTTPS, and DNS over TLS have different dependencies. When an encrypted DNS server is itself specified by hostname, the core may need a bootstrap or default resolver to obtain its address first. If that preliminary resolution fails, all subsequent queries may fail to send. If the log repeatedly times out while resolving the DNS server hostname, check the default resolver, network reachability, and the configured nameserver-policy rather than simply switching proxy nodes.

In Fake IP mode, the application first receives a reserved address; the core then restores the original domain from its internal mapping and applies the rules. Seeing a reserved address does not mean that resolution failed. Focus instead on whether the mapping exists, whether the destination domain is being intercepted correctly, and whether LAN or device-discovery domains unsuitable for Fake IP need to be excluded. Redir Host mode returns the resolved address directly to the application, so its failure logs may look different.

DNS timeout diagnostic order

1. Confirm that the configuration loads successfully and that the DNS module has initialized.
2. Check whether all servers fail or only one backup server.
3. Confirm whether queries use the direct or proxy path, and whether the related policies create a circular dependency.
4. Check that the DNS server address and protocol format are supported by the current core.
5. Disable TUN and retry through the system proxy to determine whether the issue exists only on the interception path.
6. After the domain resolves successfully, check whether TLS errors, connection timeouts, or routing failures still occur.

TUN DEVICE

TUN mode startup failures

TUN mode uses a virtual network adapter and system routes to intercept traffic from more applications, involving permissions, drivers, network interfaces, and the routing table. Its error scope is therefore broader than that of a standard system proxy. Common keywords include tun, interface, route, adapter, device, service, and operation not permitted.

First determine whether the entire core has failed or only TUN initialization. If the local HTTP or mixed port is already listening and the system proxy works with TUN disabled, the node, rules, and basic core are probably available; the failure is concentrated in the virtual-adapter path. Check the service component required by the client, runtime permissions, and other VPN, virtual-machine, or network-filtering tools on the system.

When interface creation fails, fully exit any other program that may create a virtual adapter, then restart the client. When route addition fails, check for overlapping subnets, stale routes, or insufficient permissions. If the log says that a specified network interface cannot be found, the configuration may hard-code an interface name that has changed. Switching a laptop from wired to wireless or reinstalling a network device can change the interface identifier.

TUN implementations and permission models differ across macOS, Windows, and Linux, so commands from one platform should not be applied blindly to another. If the desktop client provides a service mode or helper service, first confirm that component is working. On Linux, also verify access to the TUN device and network-management permissions. On any platform, test through the client's own enable and disable controls first rather than stacking multiple interception tools.

The network goes offline after enabling TUN, but the log shows no fatal error

Check the default route, DNS interception, and rule results. If the log shows the connection entering DIRECT but direct traffic cannot leave through the correct interface, automatic egress-interface detection may have failed. If all domain queries time out, handle the DNS path first. If only LAN devices are inaccessible, check whether the LAN subnet is being intercepted incorrectly and whether private-address rules are directing traffic as intended.

When troubleshooting TUN, keep one comparison case: disable TUN, enable only the system proxy, and access the same destination. If the system proxy works but TUN fails, continue checking the adapter and routes. If both modes fail, return to the DNS, node, and remote-connection layers.

OUTBOUND CONNECTION

Connection failures, timeouts, and TLS errors

After the core matches a rule, it connects to the destination through the selected outbound node. Logs at this stage usually include the destination domain or IP, port, network type, policy group, node name, and elapsed time. The key question is whether the connection is to the node server or to the destination site after the node connection has been established. The log module and address help distinguish these two links.

i/o timeout or context deadline exceeded

A timeout means an operation did not finish within the allotted time, but it does not identify the cause by itself. An unreachable node server, packet loss, a DNS query that never returns, or an unresponsive destination can all cause a timeout. Start with the timeout target: if it is the node server address, compare with other nodes from the same subscription; if multiple nodes in different regions time out, check the local network, DNS, and firewall first; if only a specific destination fails, inspect the rule result and destination reachability.

connection reset by peer

This message means that the peer or a device along the path reset the connection after it was established. A single occurrence may be caused by network fluctuation or the server closing the connection intentionally; persistent resets require checking the node protocol, port, transport parameters, and server status. Do not assume a client fault from reset alone. Access the same destination through another node, or different destinations through the same node, to narrow the scope quickly.

TLS handshake timeout and certificate errors

TLS handshake timeouts commonly result from poor link quality, an unreachable destination, or mismatched protocol parameters. For certificate errors, also verify the system date and time zone: an incorrect clock can make a valid certificate appear not yet valid or expired. If the node configuration includes a server name or transport-security parameters, preserve the subscription-provided content and do not delete fields whose purpose you do not understand.

network is unreachable and no route to host

These messages point to the routing layer. Possible causes include no IPv4 or IPv6 egress on the current network, a missing TUN route, an unavailable interface, or an unreachable network containing the destination address. If the log shows IPv6 attempts while the local network has no stable IPv6 connectivity, check the DNS results and the core's address-selection behavior. If both IPv4 and IPv6 fail, return to checking the system network and routes.

RULE MATCH

Rule matching and traffic routing

Sometimes the connection itself has no error, but traffic takes an unexpected path—for example, a domain that should use the proxy goes DIRECT, a LAN address is sent through a node, or a policy group selects an unavailable node. Check rule-matching logs rather than searching only for error. Debug or detailed connection logs usually show the destination, matched rule, and final policy.

Clash rules are matched in configuration order, and matching usually stops at the first hit. A broad rule placed early can override a later, more specific domain rule. The final MATCH rule handles connections that matched nothing earlier. If the log shows the wrong policy, return to the configuration and find that rule's position, inspect the rule-set contents, and check the policy group's current selection.

A policy group name is not the same as the actual node. The log may first show a connection handed to a policy group named “Auto”, followed by that group selecting a specific node. During troubleshooting, check both which group the rule selected and which option that group actually had at the time. A successful latency test only proves that the test URL was reachable at that moment; it does not guarantee access to every destination or stable long-lived connections.

DIRECT is also an explicit outbound policy. If a connection matched DIRECT and failed, check the local network, DNS, and destination site rather than expecting a proxy node to fix it. REJECT means that a rule intentionally terminated the connection, so the rejection in the log may be expected configuration behavior. If an application repeatedly requests a REJECTed domain, it may generate many entries, but that is not a core failure.

INCIDENT CHECKLIST

Log collection and troubleshooting checklist

When reporting an issue to a client maintainer, subscription provider, or other technical contact, include enough context while removing sensitive information. A single “connection failed” screenshot is not enough, and exporting hours of logs is unnecessary. Keeping several dozen seconds of continuous entries before and after the reproduction action is usually easier to diagnose.

Information to record

• Operating system and version, client name and version, and the actual core type and version.
• Whether the current mode is Rule, Global, or Direct, and whether the system proxy and TUN are enabled.
• The action performed immediately before the issue, such as updating the configuration, switching nodes, waking from sleep, or upgrading the client.
• Reproducible steps, and whether the issue is persistent or intermittent.
• The continuous log entries before and after the first anomaly, rather than only the final line.
• Comparison results after disabling TUN, switching nodes, or changing networks.

Content to remove before sharing

Logs and configurations may contain subscription URLs, authentication parameters, node server addresses, LAN device addresses, visited domains, and local file paths. Before publishing, review and redact these items individually while preserving the error type, port range, protocol category, and timeline. Do not replace every address with the same value, or you will lose key relationships such as whether an address is local or remote and whether one target or multiple targets were involved.

A fixed order from symptom to root cause

1. Confirm that the operating system itself can access the internet.
2. Confirm that configuration parsing completed and the core did not exit during startup.
3. Confirm that the local proxy and control ports are listening successfully.
4. Confirm that DNS queries return results.
5. When TUN is enabled, confirm that the virtual adapter and routes initialized successfully.
6. Confirm that the destination connection matched the expected rule and policy group.
7. Confirm that the policy group selected an available node and can connect to the node server.
8. Only then check the destination site, TLS handshake, and the application's own proxy settings.

The key principle is to handle upstream dependencies first. Do not test ports before the configuration loads, inspect application proxy settings before a port is listening, judge the destination connection before DNS completes, or blame every timeout on the node before TUN is established. Change one condition at a time and preserve before-and-after log comparisons; this usually finds the root cause faster than repeatedly changing several settings at once.