Clash Runtime Log Viewing and Analysis Guide

When Clash experiences connection failures, unresponsive rules, or DNS pollution issues, logs are the most important diagnostic tool. Many users simply report "internet doesn't work," but the logs clearly tell you exactly what went wrong.

This guide takes you from zero to proficient in reading, analyzing, and leveraging Clash logs to diagnose and fix issues.

Understanding Log Levels

Clash categorizes its logs into 5 severity levels, from highest to lowest:

Log levels are inclusive: setting INFO will output INFO, WARNING, and ERROR level logs simultaneously. Only SILENT completely disables log output.

Set the log level in your configuration file:

# Set log level
log-level: info

# Available values: silent / error / warning / info / debug

Viewing Logs Across Different Clients

Clash for Windows / Clash Verge Rev (Windows)

You can also access the Clash core log files directly via command line. Logs are stored under the user directory by default:

# Clash Verge Rev log path
%USERPROFILE%\.local\share\clash-verge-rev\logs\

# Legacy Clash for Windows log path
%USERPROFILE%\.config\clash\logs\

Clash Meta for Android (Android)

The log file path on Android is typically:

# Android log path (requires file manager access)
/sdcard/Android/data/com.github.metacubex.clash.meta.for.android/files/logs/

ClashX Pro / Clash Meta (macOS)

# macOS log path
~/.config/clash/logs/

# Or via ClashX Pro
~/Library/Logs/ClashX/

Via RESTful API

All Clash clients supporting external control allow log retrieval via API:

# Fetch real-time logs using curl (requires external-controller)
curl -X GET http://127.0.0.1:9090/logs?level=info

# Stream logs via WebSocket
wscat -c ws://127.0.0.1:9090/logs?level=info

Log Format Breakdown

Each Clash log entry follows a fixed format. Understanding each field is essential for effective log analysis.

Standard Log Format

time="2026-07-26T14:32:18+08:00" level=info msg="HTTP proxy request" caller="proxy/http.go:123"
time="2026-07-26T14:32:18+08:00" level=info msg="[Rule] match domain-keyword google" caller="engine/rule.go:456"
time="2026-07-26T14:32:19+08:00" level=error msg="dial tcp 104.21.32.1:443: i/o timeout" caller="proxy/socks5.go:78"

Common Message Patterns

Here are the message types you will frequently encounter in logs:

# Connection requests
msg="TCP Connection"          -- New TCP connection
msg="HTTP proxy request"      -- HTTP proxy request
msg="SOCKS5 proxy request"    -- SOCKS5 proxy request

# Rule matching
msg="[Rule] match ..."        -- Rule match result
msg="[DNS] resolve ..."       -- DNS resolution process

# Proxy selection
msg="[Proxy] selected ..."    -- Policy group selected a node
msg="dial ..."                -- Connecting to target address

# Error messages
msg="dial tcp ... i/o timeout"   -- Connection timeout
msg="connection refused"         -- Connection refused
msg="no such host"               -- Domain resolution failed
msg="certificate error"          -- TLS certificate error

Common Log Error Types

1. Connection Timeout (i/o timeout)

level=error msg="dial tcp 104.21.32.1:443: i/o timeout"

Meaning: Clash attempted to connect to the target server but received no response within the timeout period.

Common causes:

• The target node is offline or unreachable
• The node's network is blocked by a firewall
• Unstable network link between local machine and node
• Port blocked (e.g., TLS fingerprint detected)

Solutions: Switch nodes, check node server status, try changing ports.

2. DNS Resolution Failure (no such host)

level=error msg="dial tcp: lookup example.com: no such host"

Meaning: The domain could not be resolved to an IP address.

Common causes:

• DNS servers are unreachable or misconfigured
• The domain genuinely does not exist (typo)
• DNS has been polluted or hijacked
• In fake-ip mode, the domain was filtered out

3. Connection Refused

level=error msg="dial tcp 192.168.1.1:7890: connect: connection refused"

Meaning: No service is listening on the target port.

Common causes:

• Local proxy port failed to start properly
• Incorrect port number configuration
• Firewall blocking the local port

4. TLS/SSL Errors

level=error msg="tls: failed to verify certificate: x509: certificate signed by unknown authority"

Meaning: Certificate verification failed during TLS handshake.

Common causes:

• Incorrect system time causing premature certificate expiry detection
• Man-in-the-middle attack (DNS pollution leading to wrong server connection)
• Node server certificate has expired
• System missing root certificates

5. Subscription Download Failure

level=error msg="GET https://sub.example.com/api/v1/xxx error: context deadline exceeded"

Meaning: The remote subscription URL is inaccessible.

Common causes:

• Subscription server is down or has migrated
• Subscription link has expired
• Network issues preventing access to the subscription server

Step-by-Step Connection Troubleshooting via Logs

When encountering "no internet" or "certain websites won't load," follow these steps to diagnose using logs:

Analyzing Traffic Routing Through Logs

Logs not only help troubleshoot errors but also help you understand the actual traffic flow -- which websites go through the proxy and which go direct.

Identifying Rule Match Results

At info level and above, every rule match is recorded with the match type and result:

# Domain match
msg="[Rule] match domain-keyword google -> selected proxy HK-01"

# IP-CIDR match
msg="[Rule] match ip-cidr 192.168.0.0/16 -> DIRECT"

# GEOIP match
msg="[Rule] match geoip CN -> DIRECT"

# No rule matched (fallback)
msg="[Rule] match final -> DIRECT"

Command-Line Log Analysis

# Count rule match frequencies (Linux/macOS)
cat clash.log | grep "\[Rule\]" | grep -oP "match \K[^->]+" | sort | uniq -c | sort -rn

# View proxied domains
cat clash.log | grep "proxy" | grep -oP "domain \K[^ ]+" | sort -u

# View domains that went DIRECT
cat clash.log | grep "DIRECT" | grep -oP "domain-keyword \K[^ ]+" | sort -u

Log Persistence Configuration

By default, Clash logs are held only in memory (lost when the client closes). To persist logs, configuration changes are needed.

Method 1: Configuration File

# In config.yaml
log-level: info

# Clash Premium / Meta supports file output via startup parameters
# clash -f config.yaml 2> clash.log

Method 2: Built-in Client Features

Method 3: systemd Journal (Linux Server)

If running Clash on a Linux server with systemd, leverage journalctl for log management:

# /etc/systemd/system/clash.service
[Unit]
Description=Clash Daemon
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/clash -f /etc/clash/config.yaml
Restart=on-failure
StandardOutput=journal
StandardError=journal
SyslogIdentifier=clash

[Install]
WantedBy=multi-user.target

# View Clash logs
journalctl -u clash -f

# View recent errors
journalctl -u clash -p err --since "1 hour ago"

Log Rotation Configuration

Long-running Clash instances need log rotation to prevent unbounded log file growth:

# /etc/logrotate.d/clash
/var/log/clash/*.log {
    daily
    rotate 7
    compress
    delaycompress
    missingok
    notifempty
    copytruncate
}

Advanced: Locating DNS Issues in Logs

DNS issues are the most insidious type of failure in Clash. Many "can't connect" problems have their root cause in the DNS stage.

Enable DNS Debug Logging

At debug level, you will see the complete DNS resolution process:

# DNS query starts
level=debug msg="[DNS] resolve example.com"

# Cache lookup
level=debug msg="[DNS] cache miss for example.com"

# Query upstream DNS
level=debug msg="[DNS] query example.com IN A from tls://8.8.8.8:853"

# Response received
level=debug msg="[DNS] answer example.com IN A 93.184.216.34"

# Fake-IP assignment
level=debug msg="[DNS] fakeip example.com -> 198.18.0.10"

# Real IP resolution (for rule matching)
level=debug msg="[DNS] resolved example.com -> 93.184.216.34"

Common DNS Problem Diagnosis

Recommended DNS Configuration

# Recommended DNS configuration (anti-pollution)
dns:
  enable: true
  listen: 0.0.0.0:1053
  ipv6: false
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  fake-ip-filter:
    - "*.lan"
    - "*.localdomain"
    - "*.example"
  default-nameserver:
    - 223.5.5.5
    - 119.29.29.29
  nameserver:
    - "tls://dns.alidns.com:853"
    - "https://dns.alidns.com/dns-query"
  fallback:
    - "tls://1.1.1.1:853"
    - "https://cloudflare-dns.com/dns-query"
    - "tls://dns.google:853"
  fallback-filter:
    geoip: true
    geoip-code: CN
    ipcidr:
      - 240.0.0.0/4

Case Studies: 3 Real-World Log Analysis Scenarios

Case 1: YouTube Won't Load but Google Works Fine

User report: Google Search works normally, but YouTube keeps spinning without loading.

msg="[Rule] match domain-suffix google.com -> Proxy"
msg="dial tcp 142.250.x.x:443 via proxy HK-01"
-- Google connected successfully --

msg="[Rule] match domain-suffix youtube.com -> Proxy"
msg="dial tcp 142.250.x.x:443 via proxy HK-01"
msg="dial tcp 142.250.x.x:443: i/o timeout"
-- YouTube connection timed out --

msg="[DNS] resolve googlevideo.com"
msg="[DNS] resolve r1---sn-xxx.googlevideo.com"
msg="[Rule] match domain-suffix googlevideo.com -> DIRECT"
-- YouTube video segments went DIRECT --

rules:
  # Add before DIRECT rules
  - DOMAIN-SUFFIX,googlevideo.com,Proxy
  - DOMAIN-SUFFIX,youtube.com,Proxy
  - DOMAIN-SUFFIX,ytimg.com,Proxy

Case 2: Intermittent Disconnection Every 30 Minutes

User report: Clash works normally but disconnects every ~30 minutes for a few minutes, then auto-recovers.

-- Normal operation --
msg="[Health Check] ping HK-01: 45ms"
msg="[Health Check] ping US-01: 180ms"
msg="[Health Check] ping JP-01: timeout"
msg="[Health Check] JP-01 failed: context deadline exceeded"

-- Disconnection moment --
msg="[Health Check] ping HK-01: timeout"
msg="[Health Check] ping US-01: timeout"
msg="[Health Check] all proxies failed"
msg="[Proxy] fallback to DIRECT"

-- Recovery moment --
msg="[Health Check] ping HK-01: 48ms"
msg="[Health Check] proxy recovered"

Case 3: Specific Apps Cannot Connect (Messaging Apps)

User report: Browser works fine, but messaging apps fail to send messages or connect.

msg="TCP Connection from 192.168.1.100:54321"
msg="[DNS] resolve msg-api.example-app.com"
msg="[DNS] resolved msg-api.example-app.com -> 203.0.113.50"
msg="[Rule] match geoip CN -> DIRECT"
msg="dial tcp 203.0.113.50:443"
msg="dial tcp 203.0.113.50:443: connection established"

msg="TCP Connection from 192.168.1.100:54322"
msg="[DNS] resolve push.example-app.com"
msg="[DNS] resolved push.example-app.com -> 203.0.113.51"
msg="[Rule] match geoip CN -> DIRECT"
msg="dial tcp 203.0.113.51:8080"
msg="dial tcp 203.0.113.51:8080: i/o timeout"