Why Clash Subscription Updates Fail: Common Causes and Auto-Update Settings

First, Identify the Symptom: Three Typical Signs of Update Failure

A failed subscription update is not a single fault but a group of symptoms. Before troubleshooting, figure out which one you are dealing with:

• After clicking "Update", the spinner runs for a few seconds, then a timeout or Error message pops up, and the subscription entry's timestamp stays put.
• The client reports a successful update, yet the node list doesn't change and the timestamp is still days old — usually because a local cache was read or the new config failed to write.
• The subscription entry turns red and the node count drops to zero, with log messages such as context deadline exceeded, 403 Forbidden, or 401 Unauthorized.

Open the client's log panel and copy the full error message before digging deeper. "Update failed" alone tells you nothing; the actual error text does.

Network Causes: Update Requests Bypass the Proxy by Default

This is the most common cause of subscription update failures — and the most overlooked one.

A subscription update is essentially an ordinary HTTPS request: the client connects to the subscription URL and pulls back the node list. Most clients send this request directly, without any proxy. That leads to a seemingly contradictory situation — the nodes work fine, yet the subscription won't update. The reason is straightforward: node traffic travels through the proxy tunnel, while the update request goes out unprotected outside the tunnel. If the subscription domain is unreachable from your local network, or the route from the data center to you is poor, the direct request times out.

There are three fixes — try them in order:

1. Enable TUN mode or the system proxy, then click update once more. Once TUN takes over all system traffic, the update request is carried through the tunnel as well, bypassing the direct-connection block. See the advanced configuration page for enabling and troubleshooting TUN.
2. Turn on the "Update via proxy" option in the client's subscription settings. Clash Verge Rev offers this toggle in the subscription entry's edit menu; FlClash and Clash Meta for Android have similar settings in their subscription editors. With it enabled, updates succeed even when direct connections fail.
3. If you maintain a hand-written mihomo config, set the proxy field on the subscription source in proxy-providers so the download traffic goes through the specified proxy group:

proxy-providers:
  airport:
    type: http
    url: "https://example.com/api/sub?token=xxxx"
    interval: 43200
    proxy: Proxy
    health-check:
      enable: true
      url: https://www.gstatic.com/generate_204
      interval: 300

Without the proxy field, the default is DIRECT, which is exactly the root cause of most update failures.

Link Causes: Expiry, Resets, and Format Mismatch

If the network side checks out, examine the link itself. Subscription links fail in four typical ways:

• Plan expired or data used up: the provider cuts off the subscription response outright, returning 403 or empty content. Log in to the provider's website to check your plan status — this single step rules out half of all mistaken "the client is broken" assumptions.
• Subscription reset: after you click "Reset subscription" in the provider's dashboard, the old token is invalidated immediately, and the old address in your client will fail permanently. Copy the new link and import it again.
• Provider changed domains: once the old domain becomes unreachable or is abandoned, old links may redirect incorrectly or go silent entirely. Use the latest subscription address announced on the official site.
• UA format mismatch: many providers return different formats based on the request's User-Agent. Opening the subscription in a browser and seeing a long base64 string doesn't mean Clash can use it — Clash-family clients need YAML. When the client UA is misidentified, you get a generic format and parsing fails outright.

mihomo users can explicitly set the UA with the header field in proxy-providers, forcing the response in Clash format:

proxy-providers:
  airport:
    type: http
    url: "https://example.com/api/sub?token=xxxx"
    interval: 43200
    header:
      User-Agent:
        - "clash.meta"

Also, for links routed through third-party subscription converters, converter downtime or an unreachable domain will likewise break updates. While troubleshooting, bypass the converter and verify with the provider's original subscription link first.

Environment Causes: System Clock, Write Permissions, and Security Software

If both the link and the network are fine, the problem lies in your local environment. Listed from most to least likely:

• System clock too far off: TLS certificate validation depends on the system time; a drift of just a few minutes breaks the handshake, and the log usually mentions certificate. Correct the time, enable automatic sync, and retry.
• Traffic intercepted in the middle: corporate intranets and campus networks that perform TLS inspection cause the client to reject the intermediate certificate, and updates inevitably fail. Switch to a mobile hotspot once to confirm.
• No write permission on the config directory: the subscription downloads successfully but can't be written to disk, showing up as "updated but nothing changed". This most often hits Windows users who installed the client into Program Files and run it without elevated privileges; check the config directory permissions and free disk space.
• Security software blocking: some antivirus tools block the client's outbound requests. Add the client's main executable to the whitelist and try again.
• Client too old: the original Clash core is no longer maintained and handles newer subscription formats poorly. Switching to an actively maintained client on the mihomo core usually makes parsing problems disappear.

Auto-Update: How to Choose a Sensible Interval

Auto-update is simple in principle: the client repeats that HTTPS request at the interval you set. Choosing the interval is a trade-off — too short, and frequent requests eat into the provider's API quota and may trip rate-limiting that temporarily bans your subscription; too long, and you miss critical changes like added or removed nodes and new entry addresses, so connections drop mid-use.

A practical range is once every 6 to 24 hours. Here is where each client keeps the setting, and the units it uses:

Two points are easily confused. First, in mihomo configs the interval unit is seconds, not minutes — for 12 hours, enter 43200. Second, the health-check interval in proxy-providers controls how often node latency is tested and has nothing to do with how often the subscription is downloaded; don't edit the wrong line.

Finally, keep the habit of updating manually: when your provider announces new entry points or node changes, don't sit around waiting for the next auto-update — open the client and trigger it yourself for immediate effect.

After Updating: A Four-Step Checklist

1. Check the subscription entry's timestamp to confirm it has refreshed to the current time.
2. Check the node count and group structure against the provider's official announcements.
3. Run a latency test on the node you're using — after an update, old nodes may have gone offline, and sitting on a dead node looks like "proxied but no internet".
4. Visit a website outside mainland China in your browser to confirm the connection works; if it doesn't, return to the node list, re-test, and choose another node.

The troubleshooting order for subscription problems can be fixed once and for all: read the actual error first, then check direct connectivity, then the link status, and finally the local environment. Over ninety percent of update failures can be pinned down within these four steps. Leave the rest to auto-update — set the interval to around 12 hours and you won't have to think about it again.