Troubleshooting

Troubleshooting

🌐 English · Русский · 中文

What common situations mean and what to do. When reporting a problem, a screenshot of the Logs around connect/import is worth more than any description.

A node "pings" but pages don't load

The latency test runs from the core directly to a test URL, bypassing the tunnel — so a green ping only proves the core can reach the server, not that TUN-routed traffic works. Usual causes:

• DNS is failing. If lookups don't resolve, you'll see dns resolve failed: couldn't find ip in Logs — for proxy servers and direct sites. First try Settings → Connection → Smart DNS fallback: proxied domains then resolve through the proxy, which fixes the common case of an ISP resolver that is slow, blocked or poisoned. To change the resolvers themselves you have to edit the profile's dns: block — there is no DNS-server field in Settings.
• Broken IPv6. Errors like dial tcp [2600:…]: The requested address is not valid in its context mean your machine has no working IPv6 route but the config returns IPv6 addresses. Make sure Settings → Connection → Enable IPv6 DNS is off — that is the default, and it keeps both the top-level ipv6 flag and dns.ipv6 disabled. Only turn it on if your network really has IPv6.
• Rule lists pulled through a dead proxy. If a subscription fetches its rule providers proxy: through a node that's down, Rule mode has nothing to match on. Pick a working node or check with your provider.
• MTU / UDP. QUIC-based protocols (Hysteria2, TUIC) can ping yet stall real traffic if the TUN MTU is too high. Try Settings → TUN → MTU = 1408, or test in System-proxy mode to confirm it's the TUN path.

Import succeeds, but nothing works after connecting

Almost always the rule-provider-through-a-dead-node case above, or a DNS problem. Open Logs and look for initial rule provider … error or dial … i/o timeout — the address in the dial line tells you which node couldn't be reached. Pick a different node and reconnect.

TUN won't come up / connects then drops

• SlothClash verifies the TUN adapter after bring-up and will restart the core once if it didn't come up cleanly; give it a few seconds.
• Make sure the helper service is installed and healthy — if the app shows a reinstall-service banner, follow it (see the section below). A stale service can block TUN.
• On Windows, third-party network filters can interfere. On macOS, a utun … Operation not permitted usually means another network filter (e.g. Cisco AnyConnect) is blocking the tunnel — quit it and retry.

The "reinstall helper service" banner

SlothClash shows this banner in three different situations. All three are fixed the same way: click the button on the banner and accept the UAC prompt.

1. The service is older than the app requires. The desktop app and the privileged service must match; they drift after an app update.

2. "Helper service must be reinstalled to allow the updated core." The service only starts a Mihomo core whose SHA-256 matches a hash pinned when the service was installed — that is what stops anyone from swapping the core binary for something else. When an app update ships a new core, the old pin no longer matches and the service refuses to start it, so connecting fails.

The installer usually re-pins the service automatically during an upgrade, so most people never see this. If you do, the reinstall button records the new hash and connecting works again.

3. "Helper service is unavailable — reinstall to restore it." The service is registered but doesn't respond. Older versions kept the service binary in a temporary folder that the system could clean up, leaving the service unable to start. Reinstalling puts it back — and versions from 2.4.0 on install it next to the app in Program Files, so this fixes itself permanently after one reinstall.

After updating to a version that requires service 2.4.0, seeing this banner once is expected: that release moves the service binary out of the temp folder into an admin-only location. Reinstall once and it won't come back.

Windows: Visual C++ runtime

SlothClash needs the Microsoft Visual C++ runtime. The installer detects a missing one and installs it silently — you only see a progress line, no prompt.

If that download fails (no internet during install, a corporate proxy, a blocked domain), the installer tells you so. Install it by hand from aka.ms/vs/17/release/vc_redist.x64.exe and run the SlothClash installer again.

Other devices on my network can't use this machine as a proxy

By default SlothClash listens on localhost only, so pointing your phone at this PC's IP does nothing. Turn on Settings → Connection → Allow LAN binding and the local proxy becomes reachable from your network. (If your profile pins a loopback bind-address, the app rewrites it so the setting actually takes effect.)

Only enable this on networks you trust — anyone on the same network can then route their traffic through your tunnel.

Reading Logs

Logs shows the core's own messages. Useful lines:

Line	Meaning
dns resolve failed: couldn't find ip	DNS couldn't resolve — see the DNS section above
dial tcp [2600:…]: … not valid in its context	Broken IPv6 — turn off Enable IPv6 DNS in Settings → Connection
[TCP] dial <group> … i/o timeout	The node <ip> is unreachable
initial rule provider <name> error	A rule list failed to download (often through a dead node)

Related

• Settings — TUN stack, MTU, DNS
• Profiles & Nodes — switching nodes