Fixing Clash Subscription Update Failures & Auto-Update Setup Guide

How subscription updates actually work

A subscription link is just a URL generated by your provider that returns a Clash config when requested — usually plain YAML, sometimes a base64-encoded node list. When you hit "Update" in the client, four things happen in order: an HTTPS request to the subscription URL, downloading the response, parsing it into a config, then writing it locally and switching to it.

If any of these four steps fails, the UI just shows "Update failed" with no further detail. That's why troubleshooting follows a fixed order: first check whether the network can even reach the subscription URL, then verify the link itself is still valid, and finally look at client-side caching and parsing issues. Working through this order usually pinpoints the exact failure point within minutes.

Common causes and the order to check them

1. Network can't reach the subscription URL

A blocked subscription domain or DNS tampering is the most common cause of update failures. The quickest test: paste the subscription link straight into your browser's address bar. If it returns a long block of text, the network layer is fine. If it hangs or errors out, that link simply can't reach the server on this network.

• If you already have a working node, connect to it and enable the system proxy before updating the subscription. Clash Verge Rev's subscription settings include a "Use system proxy" toggle — turning it on routes the update request through your active proxy and noticeably improves success rates.
• If you don't have a working node on hand, open the subscription link in a browser on a network that can reach it (mobile data works), save the response as a .yaml file, then add it via the client's "Import from local file" option.
• Switch your system DNS to a public resolver like 8.8.8.8 or 1.1.1.1 to rule out DNS tampering as the cause of resolution errors.

2. Subscription link has expired

Plan expiration, exhausted data allowance, or the provider resetting your subscription token will all turn a working link into a dead one. If your browser returns a 401, a 403, or a plain-text error instead of a config, the link has almost certainly expired.

Fix: log in to your provider's dashboard and copy a fresh subscription URL, then remove the old entry in the client and re-add it with the new address. Note that some providers offer separate links for Clash, Clash Meta, and other formats — make sure you copy the one labeled for Clash or mihomo.

3. Client-side caching and parsing failures

Two typical symptoms. First: the update appears to succeed, but the node list doesn't change — this usually means the client is holding onto a cached config, and removing then re-adding the subscription fixes it. Second: an outright parsing error, often because the response isn't in Clash format. Some providers vary their response based on User-Agent, and if the client isn't recognized correctly, you may get a node list in a different protocol that Clash simply can't parse.

Fix: check whether the subscription URL includes a format parameter such as target=clash; if not, run it through a subscription converter to generate a Clash-format link. It's also worth noting that mihomo (Clash Meta) has the best compatibility with newer config fields — configs that fail to parse on older cores often work on the first try with a mihomo-based client.

4. System clock drift breaking TLS verification

If your system clock is significantly off from real time, the TLS handshake will treat the server's certificate as invalid, and logs will show certificate expired or references to x509. Enable automatic time sync, let it correct, then retry. This shows up most often on devices that have been powered off for a long time or after a motherboard reset.

Setting up scheduled auto-updates

Node lists change on the provider's schedule, and relying on manual updates means you'll eventually forget. Here's where to find auto-update settings in each client:

• Clash Verge Rev (Windows / macOS / Linux): On the "Profiles" page, find your subscription entry and click the edit icon, then set "Update Interval" in minutes — 1440 means once a day. Leave it blank or set it to 0 to disable auto-update. It's also worth enabling "Use system proxy" at the same time.
• Clash for Android: On the "Profile" page, tap the menu next to your subscription entry, choose Edit, and set the "Auto Update Interval" (also in minutes). Keep in mind Android's background restrictions — the timer stops once the app is killed, so it's safer to update manually every few days as well.
• Clash for Windows: Right-click a subscription entry on the Profiles page to set an update interval. This client is no longer maintained, so long-term users should consider migrating to Clash Verge Rev.
• ClashX Meta (macOS): The config menu under the menu bar icon offers both manual and automatic update options.

There's no UI toggle for mihomo running as a CLI process — the subscription is the config file itself, so set up a cron job to fetch it and trigger a hot reload:

# Update the config at 06:00 daily and tell mihomo to hot-reload it
0 6 * * * root curl -fsSL "https://example.com/sub?target=clash" -o /etc/mihomo/config.yaml.tmp \
  && mv /etc/mihomo/config.yaml.tmp /etc/mihomo/config.yaml \
  && curl -fsS -X PUT "http://127.0.0.1:9090/configs" \
       -H "Content-Type: application/json" \
       -d '{"path":"/etc/mihomo/config.yaml"}'

Two details worth noting: download to a temporary file first, then mv it into place — this avoids ending up with a half-written config if the network drops mid-download. The PUT /configs call triggers a hot reload in mihomo without restarting the process, but only if external-controller is enabled and listening on port 9090.

Manual updates and verifying results

While troubleshooting, stick to manual updates: click the "Update" button on the Profiles or Config page in desktop clients, or pull down to refresh on the Profile page in Clash for Android. After each update, check three things:

1. Whether the timestamp next to the subscription entry just refreshed;
2. Whether the node list on the Proxies page shows new nodes and drops ones that are no longer available;
3. Whether running a latency test on any node returns an actual value instead of timing out.

If the update succeeds and the timestamp updates, but every single node times out, the problem isn't the subscription — it's node availability or your local network setup. Work through the standard first-connection checklist: try a different node, try a different network, and check the status of your system proxy and TUN mode.

FAQ