Problem Diagnosis Process
When ClashX cannot connect, a systematic diagnosis process can help you quickly identify the issue. Following the correct troubleshooting order can avoid wasting time on wrong directions.
Quick Diagnosis Checklist
First perform these basic checks:
View Error Messages
ClashX error messages provide important clues:
View Log Steps
1. Click menu bar ClashX icon
2. Select "Help" > "Show Logs"
3. Look for lines containing "error", "failed", "timeout"
4. Record error codes and timestamps
Use process of elimination: test if all nodes cannot connect, or only specific nodes. This helps determine if it's a node issue or local configuration issue.
Connection Failure Troubleshooting
Common Connection Error Types
Take appropriate measures based on different error messages:
| Error Type | Symptom | Possible Cause | Solution |
|---|---|---|---|
| Connection timeout | Long wait with no response | Node failure or network blockage | Switch nodes |
| Connection refused | Immediately rejected | Wrong port or service not running | Check port configuration |
| Authentication failed | Authentication failure prompt | Wrong password or key | Update subscription or modify config |
| Network unreachable | Network unreachable | Local network problem | Check network connection |
Node Connection Testing
Systematically test node availability:
- Click "Proxy" > "Benchmark"
- Wait for all nodes to complete testing
- Select node with lowest latency
- If all nodes fail, update subscription
Subscription Update Issues
If connection issues are caused by subscription:
1. Check if subscription link is valid
2. Manually update subscription config
3. If update fails, contact service provider
4. Backup plan: use backup config file
DNS Problem Resolution
DNS Failure Symptoms
DNS issues typically show these symptoms:
- Webpage shows "cannot resolve domain name"
- Can ping IP but cannot access domain
- Some websites work, some don't
- Connection speed abnormally slow
Modify DNS Configuration
Optimize ClashX DNS settings:
Recommended DNS Configuration
dns:
enable: true
ipv6: false
enhanced-mode: fake-ip
fake-ip-range: 198.18.0.1/16
# Domestic DNS
nameserver:
- 119.29.29.29
- 223.5.5.5
- 114.114.114.114
# Global DNS (encrypted)
fallback:
- tls://1.1.1.1:853
- tls://8.8.8.8:853
- https://dns.google/dns-query
# Routing rules
fallback-filter:
geoip: true
geoip-code: CN
ipcidr:
- 240.0.0.0/4
- 0.0.0.0/32
Clear DNS Cache
Flush system and ClashX DNS cache:
Clear Cache Commands
# macOS: Clear system DNS cache
sudo dscacheutil -flushcache
sudo killall -HUP mDNSResponder
# Restart ClashX to clear app cache
DNS Leak Testing
Verify DNS is working correctly:
Visit dnsleaktest.com to check if DNS queries are properly proxied. If displayed DNS servers don't match your configuration, there is a DNS leak.
Certificate Error Handling
Certificate Error Types
Certificate issues you may encounter when accessing HTTPS websites:
• Certificate expired
• Certificate not trusted
• Certificate domain mismatch
• Man-in-the-middle attack warning
Install ClashX Certificate
Steps to resolve certificate trust issues:
- Click ClashX menu > "Certificate" > "Install CA Certificate to System"
- Enter administrator password to confirm installation
- Open "Keychain Access" app
- Find ClashX CA certificate
- Double-click certificate, expand "Trust" option
- Set "When using this certificate" to "Always Trust"
Certificate Issue Troubleshooting
If problems persist after installing certificate:
- Check if system time is correct (certificates are time-sensitive)
- Regenerate and reinstall certificate
- Check if other security software is interfering
- Try disabling HTTPS decryption feature
Special Website Certificate Issues
Some banking or payment websites may be incompatible with HTTPS decryption. You can add DOMAIN rules to let these websites go DIRECT, bypassing proxy.
Network Configuration Issues
System Proxy Settings Check
Verify macOS system proxy configuration:
Firewall Configuration
Ensure firewall doesn't block ClashX:
Firewall Settings Steps
1. Open "System Preferences" > "Security & Privacy"
2. Click "Firewall" tab
3. Click "Firewall Options"
4. Ensure ClashX is allowed to accept incoming connections
Port Conflict Check
Check if ClashX ports are occupied:
Check Port Commands
# Check port usage
sudo lsof -i :7890
sudo lsof -i :7891
sudo lsof -i :9090
# If the port is in use, change it in ClashX config
VPN Conflict Issues
Running multiple proxy tools simultaneously may cause conflicts:
When using ClashX, it's recommended to close other VPN or proxy tools (like ShadowsocksX, V2RayU, Surge, etc.). If you must use them simultaneously, ensure they use different ports.
Advanced Troubleshooting
Complete ClashX Reset
When other methods don't work, try complete reset:
Reset Steps
# 1. Quit ClashX completely
# 2. Remove config files
rm -rf ~/.config/clash
# 3. Remove log files
rm -rf ~/Library/Logs/ClashX
# 4. Restart ClashX
# 5. Re-add subscription or config
Be sure to backup your configuration files and subscription links before resetting! You can copy ~/.config/clash directory to a safe location.
Reinstall ClashX
If the app itself has problems:
- Completely quit ClashX
- Move ClashX.app to Trash
- Empty Trash
- Download latest version from official GitHub
- Install and reconfigure
Use Enhanced Mode
If system proxy mode doesn't work, try enhanced mode:
Enhanced mode can capture traffic from apps that don't follow system proxy settings. Check "Enhanced Mode" in ClashX menu to enable.
Seek Help
If above methods don't solve the problem:
- Search GitHub Issues for similar problems
- Join Telegram community for help
- Contact your proxy service provider technical support
- Provide detailed log information for diagnosis
| Resource | Purpose | Link |
|---|---|---|
| GitHub Issues | Report bugs and issues | github.com/charlessnow/ClashX |
| Official docs | View detailed documentation | clash.wiki |
| Community forum | Share experiences | Various tech forums |
