How to Read Clash Runtime Logs: Common Errors and Troubleshooting Steps

First identify which part of the connection the log describes

Clash, Clash Meta (mihomo), and their GUI clients commonly handle system proxying, DNS, rule matching, node connections, TUN forwarding, and subscription updates at the same time. An error in the log does not mean the entire client has stopped working; one failed connection does not mean the current node is completely unusable. Start by identifying which layer reported the error, then adjust the relevant settings.

A typical connection log includes the time, log level, inbound type, destination address, matched rule, policy group, actual node, and error text. The order varies slightly between clients, but the core information is the same. For example:

20:14:08 INF [TCP] 127.0.0.1:53142
--> api.example.com:443
match DomainSuffix(example.com)
using Proxy[HK-01]

20:14:13 ERR dial HK-01
198.51.100.20:443
dial tcp 198.51.100.20:443: i/o timeout

This entry shows that the local application sent a TCP request from 127.0.0.1 to api.example.com:443. The domain matched a suffix rule, the policy group selected HK-01, and Clash then timed out while connecting to the node server at 198.51.100.20:443. The failure occurred between the local machine and the node server, not because the destination website actively refused access.

Always extract these five details from the log

1. Timestamp: Does the error match the action you just took? Reproduce it once, then check entries from the same minute.
2. Protocol and inbound: TCP, UDP, HTTP, SOCKS, or TUN. Some issues affect only UDP, while web pages may continue to load normally.
3. Destination: Determine whether the logged domain or IP belongs to the node server, subscription URL, DNS server, or final website.
4. Rule and policy: Check which rule matched and whether the policy group ultimately selected DIRECT, REJECT, or a specific node.
5. Final error: Go network errors usually put the most specific cause at the end, such as i/o timeout, connection refused, or no such host.

What info, warning, and error mean

Log levels describe event severity; they do not directly determine troubleshooting priority. A background health check may generate an error that affects only one backup node, while an info-level rule entry may show that the current site was blocked by a REJECT rule. Read the level together with the destination and policy result.

Failed entries can also appear in normal logs

A browser may try IPv4, IPv6, HTTP/3, and regular HTTPS at the same time. If one path fails, it may immediately switch to another, so the page can still open. Node health checks also access test addresses periodically; a timeout for one node means only that check did not finish, not that the node currently in use was disconnected.

To decide whether action is needed, watch for three signals: whether the same error keeps recurring, whether its destination is the service you cannot access, and whether the error disappears immediately after switching nodes or disabling a feature. A one-off background error with no visible impact can be noted for later; do not change several settings at once.

dial tcp timeout: the connection did not complete within the time limit

dial tcp ...: i/o timeout means the TCP connection was not established before the timeout. If the address in the error is the node server's IP, first check the network path from the local machine to the node. If it is the final website, check the path from the proxy node to the destination. A timeout differs from an explicit port refusal: the remote side did not return a usable response in time.

Common causes

• The node server is temporarily offline, or its port has changed.
• The current Wi-Fi, mobile network, or upstream router cannot reach the server.
• A firewall is dropping traffic on the specific port.
• IPv6 routing is unavailable, but the node domain resolves to an AAAA record first.
• A TUN routing loop sends the node connection back into Clash.
• The node is reachable, but the TLS handshake or subsequent transfer keeps timing out.

Run four comparison tests in order

1. Switch to another node in the client and repeat the same request. If the new node works, the issue is limited to the original node or its route.
2. Switch networks, such as moving from home Wi-Fi to a phone hotspot. If the same node works again, check the router, firewall, and current carrier route.
3. Temporarily disable TUN and keep only the system proxy enabled, then visit the same address. If the system proxy works but TUN times out, focus on routing, DNS hijacking, and interface selection.
4. Check the address that timed out. A node IP timeout and a destination-domain timeout follow different paths; do not judge solely by the website name.

Common local Clash proxy ports include HTTP port 7890 and SOCKS port 7891. You can also use mixed-port: 7890 for both. These numbers are configurable. Before troubleshooting, check the actual values under “Settings” → “Port Settings” or “Settings” → “Parameters” in the client, and confirm that the system proxy uses the same port.

connection refused: the address is reachable, but the port rejected the connection

connect: connection refused or dial tcp ...: connect: connection refused usually means the data reached the destination host, but no service is listening on the specified port, or a firewall actively returned a refusal. It often appears faster than a timeout.

ERR dial tcp 127.0.0.1:7890:
connect: connection refused

ERR dial tcp 203.0.113.8:443:
connect: connection refused

The first points to 127.0.0.1:7890, showing that the local application tried to connect to the local proxy port, but nothing was listening there. The Clash core may not have started, the port may have been changed, or the client may have enabled only its SOCKS port. The second points to a remote IP and usually indicates an incorrect node port, a stopped node service, or an active refusal by the server firewall.

Check these locations when a local port is refused

• Confirm on the client's status page that the core is running rather than stuck in a startup-failed state.
• Open “Settings” → “Port Settings” and check the actual HTTP, SOCKS, and Mixed Port values.
• In the browser or application's manual proxy settings, set the address to 127.0.0.1 and use the same port currently listened to by Clash.
• If the configuration uses mixed-port: 7890, both HTTP and SOCKS clients can connect through that port; do not assume that 7891 must also be enabled.
• Check the beginning of the log for bind: address already in use. This means another process occupies the port, preventing the core from listening.

What to do when a remote port refuses the connection

Update the subscription first, then confirm whether the node server address or port has changed. If only one node reports the error, switch nodes and record the affected entry. If every node in the same subscription is refused, check whether the subscription has expired, whether the configuration still references an old server, and whether the network is rewriting the connection through a transparent gateway.

DNS resolution failures: distinguish domain problems from connection problems

Common DNS errors include no such host, DNS request failed, server misbehaving, and context deadline exceeded. A DNS failure occurs while converting a domain name into an IP address. If the log already shows a connection to a specific IP, such as 198.51.100.20:443, a later timeout is usually not a domain-resolution failure for that connection.

Separate the three types of DNS failure

mihomo DNS settings can distinguish the default server used to resolve node domains from the nameserver used for ordinary queries. The compact example below is intended to clarify the structure; adjust the actual addresses for your network:

dns:
  enable: true
  listen: 0.0.0.0:1053
  ipv6: false
  enhanced-mode: fake-ip
  default-nameserver:
    - 1.1.1.1
    - 8.8.8.8
  nameserver:
    - https://1.1.1.1/dns-query
    - https://8.8.8.8/dns-query

default-nameserver uses IP addresses and mainly resolves the domains of DoH servers or proxy nodes themselves, avoiding a dependency loop in which the DNS server must be resolved before it can resolve anything. listen: 0.0.0.0:1053 is the Clash DNS listener address; it does not automatically send every system query to that port. TUN mode usually also requires DNS hijacking.

Special behavior in Fake-IP mode

Fake-IP returns a mapped address to the application while Clash retains the original domain internally for rule matching. An address in the 198.18.0.0/16 range is usually a mapping result, not the real website server. If a local device, game, or enterprise application is incompatible with Fake-IP, add a domain filter or compare it with redir-host mode; do not assume DNS is broken merely because a mapped address appears.

How to read TLS, EOF, and context deadline exceeded

TLS handshake timeout

TLS handshake timeout means TCP may have been established, but the TLS handshake did not finish within the time limit. Common causes include packet loss, an overloaded node, interference from an intermediate device, and an unsuitable MTU. Switch nodes and networks first. If it occurs only under TUN, compare the common MTU of 1500 with 1400 or 1280, testing one change at a time. Do not change MTU, DNS, and the proxy protocol simultaneously, or you will not know which change helped.

x509 certificate errors

x509: certificate has expired means the certificate has expired; x509: certificate is valid for ... means its domain does not match the connection target; certificate signed by unknown authority means the certificate chain is not trusted in the current environment. First verify the system date, time, and time zone, then check the node domain, SNI, or server name setting. Disabling certificate verification at random hides configuration errors and is not a suitable long-term fix.

EOF and unexpected EOF

EOF means the peer ended the data stream. A single EOF may result from a normal server disconnect; if it occurs at the same stage on every request, check the protocol parameters, node service status, or intermediate network devices. unexpected EOF emphasizes that the connection ended before the expected data was fully read. Switching nodes is the quickest comparison test.

context deadline exceeded

This is a generic operation-timeout message and cannot, by itself, identify whether the failure occurred during DNS, node dialing, a health check, or a subscription download. Check the operation name earlier on the same line and the 5 to 10 lines around it. If it follows proxy provider, the issue is likely a subscription or provider update timeout; if it follows a DNS request, check upstream DNS; if it follows a node address, troubleshoot it as a connection timeout.

Port conflicts, configuration errors, and core startup failures

If the log contains only a few lines and the client then stops, the issue is usually not node quality but an incomplete core startup. Configuration syntax errors and listener port conflicts are the two most common causes.

address already in use

listen tcp 127.0.0.1:7890:
bind: address already in use

This means another process already occupies 7890. It may be another proxy client, a core process left running after an earlier exit, or a local development service. Fully quit other proxy programs and restart the client. If the conflict remains, temporarily change Mixed Port to 7892 under “Settings” → “Port Settings”, and change the system proxy to the same number. Changing only the Clash port while leaving the system proxy unchanged makes the browser keep using the old port and produce connection refused.

Configuration parsing errors

YAML is sensitive to indentation and data types. The log may show a specific line, such as yaml: line 42: did not find expected key. Check that line and the one above it first, making sure indentation uses spaces, a space follows each colon, and list items begin with -. Node names referenced by policy groups must also match the actual names.

mixed-port: 7890
mode: rule

proxy-groups:
  - name: Proxy
    type: select
    proxies:
      - HK-01
      - DIRECT

rules:
  - DOMAIN-SUFFIX,example.com,Proxy
  - MATCH,Proxy

If startup fails immediately after a subscription update, switch back to the last working configuration under “Config” → “Profiles” in the client, then run a syntax check on the new configuration. Do not make a dozen changes in succession to a configuration with an unknown issue. Change one item at a time, save, reload, and watch the first error.

What to focus on when troubleshooting TUN logs

TUN handles a broader range of traffic than the system proxy, exposing connections from UDP, local networks, system services, and applications that ignore proxy settings. A sharp increase in log volume after enabling TUN is normal. Focus instead on continuous retries, routing loops, interface creation failures, and DNS hijacking anomalies.

Common TUN problems

• operation not permitted: Insufficient permission to create the interface or modify routes. Check client permissions and the TUN service installation status.
• network is unreachable: The current routing table has no usable path to the destination, commonly due to broken IPv6 or incorrect interface selection.
• device or resource busy: The TUN device is being used by another instance or another VPN.
• Connection loop: Traffic to the node server is entering TUN again, causing the same destination to repeat rapidly in the log. Check auto-routing, interface detection, and node-address exclusion logic.
• UDP timeout: This may affect only games, voice calls, or QUIC, and may not affect ordinary TCP websites.

Binary-test system proxy and TUN separately

1. Record the current configuration and confirm that the rule mode, node, and DNS settings remain unchanged.
2. Disable TUN, enable only the system proxy, and test the browser and subscription update.
3. Enable TUN again, disable the system proxy, and test the same destination.
4. If only TUN fails, check interface permissions, auto-routing, MTU, DNS hijacking, and other VPNs.
5. If both modes fail, return to the node, DNS, rules, and local port for further troubleshooting.

On Android, also confirm that VPN permission is not occupied by another VPN app. Under system “Settings” → “Apps” → “Clash Client” → “Battery”, allow a background-running policy appropriate for your needs. When TUN interface creation fails on Windows, check the client's service mode or administrator permissions. On macOS, verify the network-extension authorization status in System Settings.

The rule matches correctly, but the website still cannot be reached

Entries such as match, using, or a rule name only show that Clash selected a policy; they do not confirm that the connection succeeded. Continue reading the same connection for dial, TLS, or DNS errors.

Check the policy result first

• Matched DIRECT: the connection bypasses the proxy. If the destination requires a node, check rule order and domain-matching behavior.
• Matched REJECT: Clash actively blocked the connection according to the rule. Check whether ad-blocking or custom rules matched it incorrectly.
• Matched a policy group: confirm which node the group actually selected rather than looking only at the group name.
• Matched MATCH: none of the preceding specific rules matched, so the connection entered the final fallback policy.

Clash evaluates rules from top to bottom and usually stops after the first match. Specific domain rules should appear before broad rules, with MATCH as the final fallback. For example:

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

If MATCH,DIRECT appears near the top of the list, later domain rules will not run as intended. After editing, reload the configuration and confirm in the log that a new connection matches the target rule. Existing connections may continue using the old policy, so close the relevant application or wait for old connections to end before testing.

A repeatable workflow for troubleshooting logs

Effective troubleshooting relies on controlled comparisons, not changing the configuration, node, DNS, and network all at once. The workflow below applies to common issues such as inaccessible websites, failed subscription updates, node latency timeouts, and no network under TUN.

1. Record the environment: Note the client version, core type, current network, proxy mode, whether TUN is enabled, and the actual listening ports.
2. Clear the log: Open “Logs” or “Settings” → “Logs” and set the level to info; switch temporarily to debug only when more detail is needed.
3. Reproduce once: Perform one clearly defined action and note the exact time.
4. Find the target: Filter entries by domain, IP, port, or policy-group name.
5. Locate the layer: Determine whether the failure occurred at the local port, DNS, rules, node dialing, TLS, destination service, or TUN routing.
6. Run one comparison: Change only one variable, such as the node, network, TUN state, or upstream DNS.
7. Verify the result: Clear the log and reproduce the issue again, confirming that the original error is gone and has not turned into a new one.

What to prepare before sharing logs

When reporting to a client maintainer, subscription provider, or network administrator, complete environment details are more useful than a screenshot saying “connection failed”. Include the client name and version, mihomo core version, operating system version, proxy mode, TUN status, time of failure, reproduction steps, and relevant log excerpts.

Logs may contain visited domains, node names, server IPs, local LAN addresses, and configuration paths. Before sharing them, hide subscription URLs, authentication details, usernames, passwords, and access tokens. Do not remove all context around the error; keeping 10 to 20 lines before and after the target connection is usually enough to determine the rule selection and failure stage.

A concise format for reporting

Client: name and version
Core: mihomo version
System: operating system and version
Mode: Rule / TUN enabled
Port: mixed-port 7890
Symptom: browser times out when accessing the specified domain
Time: 20:14:08
Comparison: recovered after switching nodes
Error: dial tcp ...: i/o timeout

The key to troubleshooting logs is to identify the connection stage first, then run a single-variable comparison. timeout indicates that an operation did not finish in time, refused indicates an explicit port rejection, DNS errors occur during domain resolution, and rule logs show only the selected policy. TUN errors require additional checks of permissions and routing. Validate each stage along the path from “local application → Clash inbound → DNS and rules → node → destination service” to narrow the issue to one actionable setting or network layer.