Clash Subscription Update Failed: Common Causes and Auto-Update Interval Settings

First identify where the update failed

“Update subscription” in a client is not a single action. It typically includes DNS resolution, connection setup, sending an HTTP request, receiving the response, parsing the configuration, writing the local file, and reloading the core. When the interface only shows “Update failed,” use the logs or response body to identify the exact stage. Repeatedly clicking the button usually does not change the result and may trigger the subscription service’s rate limit.

Common desktop clients place subscriptions under “Configurations,” “Subscriptions,” or “Profiles.” In a client using the mihomo core, start by opening “Configurations” → “Subscriptions,” manually update the target profile once, then check the entries created at the same time on the “Logs” page. If the client offers log levels, use Info while troubleshooting; switch to Debug temporarily only when the error details are insufficient.

Separate subscription downloads from node connectivity

A successful subscription update only means that the client retrieved and parsed the configuration; it does not mean that every proxy node in it can connect. Conversely, working nodes do not prove that the subscription URL is still valid. The local configuration may be a cache saved days ago: its nodes can still work even though the original subscription token has expired.

• Update fails but old nodes still work: focus on the subscription URL, authentication, and update path.
• Update succeeds but every node times out: focus on node parameters, network restrictions, and system time.
• Node count drops to 0: check the server response body first, not just the HTTP status code.
• The downloaded configuration cannot be enabled: check YAML syntax, field compatibility, and the core version.

Expired, truncated, or unauthorized subscription links

A subscription URL usually contains an access token. If the token is reset, the plan changes, the link expires, or the server migrates the route, the old URL may return 401, 403, 404, or 410. Some services return status 200 while the body is actually a login page or a JSON error, so “download complete” can still be followed by a parsing failure.

Confirm that the full link was copied

Long links can lose trailing characters when passed through chat apps, QR-code scanners, or manual line breaks. Also watch the & in query parameters: when copying from a webpage, use the real link from the browser’s address bar rather than pasting the escaped text shown in HTML. The link must not contain spaces, Chinese quotation marks, or line breaks at either end.

1. Return to the subscription service’s management page and copy the Clash or mihomo subscription URL again.
2. Create a temporary subscription in the client instead of deleting the old profile immediately.
3. Run a manual update and compare the node count, proxy-group names, and update time.
4. After confirming that the new configuration loads, disable the expired subscription.

A subscription link is an access credential. Do not post it in public logs, screenshots, or online YAML validators. When sharing an error, keep the domain and status code if needed, but redact tokens in the path and all query parameters.

Check the status code and response type from the command line

A browser may redirect automatically to a login page or use request headers different from Clash. Command-line testing makes the status code and response headers easier to inspect. On Windows, run curl.exe in PowerShell; on macOS and Linux, use curl directly. The examples below use a reserved domain and contain no real subscription credentials.

curl -I -L --max-time 15 "https://sub.example.com/clash/demo-token"
curl -L --max-time 15 -o subscription.yaml "https://sub.example.com/clash/demo-token"

-I requests headers only, but some subscription servers do not accept HEAD requests. If the first command returns 405, rely on the second command’s actual GET request. After downloading, inspect the beginning of the file: HTML commonly starts with <!doctype html> or <html, JSON errors often start with a brace, and Clash YAML usually contains fields such as proxies:, proxy-groups:, and rules:.

User-Agent checks and format incompatibility

Some subscription services return different formats based on the User-Agent or allow only specific client identifiers. If a browser works but a client update returns 403, or the same URL returns different content in different clients, check the UA. Common identifiers include clash, Clash.Meta, and the client’s own name, but the accepted value depends on the server configuration; repeatedly changing it at random is not a reliable test.

First check the subscription service’s documentation for its recommended UA. If the client provides a setting, look under “Settings” → “Parameter Settings” or in the subscription editor for options such as “User-Agent” or “Subscription request headers.” Menu names vary by client version. If no such option exists, do not edit the core configuration blindly: proxy rules in the main configuration are not the same as the HTTP headers used by the subscription manager.

curl -L --max-time 15 \
  -A "Clash.Meta" \
  -o subscription.yaml \
  "https://sub.example.com/clash/demo-token"

If the default request returns 403 but the UA explicitly required by the provider returns 200 with valid YAML, the issue is likely request-header validation. If both requests return the same error, continue checking the token, source IP, request frequency, and service status.

A Base64 node list is not the same format as Clash YAML

A generic subscription may be a block of Base64 text that decodes to multiple URI lines, while a Clash configuration is usually structured YAML. If the client accepts only Clash YAML, importing a generic subscription may produce “missing proxies,” “unable to parse configuration,” or a node count of 0. Select Clash, Clash Meta, or mihomo as the output type on the server instead of changing the file extension manually.

mihomo maintains broad compatibility with Clash configurations, but older Clash cores may not recognize extension fields. New protocol parameters, rule-provider options, and DNS fields can trigger unknown-field or load errors in older cores. Check the client’s core version first, then select a matching subscription template. Updating the graphical client does not necessarily switch the core automatically; confirm the core version separately under “Settings” → “Core” or on the “About” page.

A YAML file can open and still fail to load

• Indentation at the same level must be consistent; do not mix tabs and spaces.
• Every node or provider referenced by a proxy group must exist.
• The target proxy group used in rules must already be defined.
• Ports must be valid integers and must not be corrupted by quotation marks, non-ASCII punctuation, or comments.
• If the server returns an empty file, the client may keep the old configuration or report that parsing finished without finding any nodes.

When the subscription itself is generated by the server, avoid making long-term manual edits to the downloaded file. The next automatic update will overwrite them. If you need to preserve local DNS, TUN, or rule settings, prefer the client’s override, merge-configuration, or scripting features, and verify the merge result after every client upgrade.

Should updates use a direct connection or a proxy?

The route used for subscription requests is one of the easiest variables to overlook. When the subscription domain is directly reachable, direct access is simplest and does not depend on an existing node. When the domain is reachable only through a proxy, enable the client’s “Update through proxy” option or make the updater use the current proxy. Implementations differ: some clients use the system proxy, while others call the current core port directly.

Prefer an update path that can start independently

If updating the subscription depends on nodes from that same subscription, it creates a bootstrapping dependency: without a working old node, the client cannot reach the subscription server; without a successful update, it cannot obtain new nodes. A safer approach is to keep the most recent working configuration and avoid clearing the local file when an update fails.

Subscription-management requests do not necessarily pass through Clash rules. Some clients download subscriptions directly within their own process, while others send requests to the local mixed-port. Even if the rules specify DIRECT for the subscription domain, that does not guarantee that the client updater will use those rules. Follow the client documentation, update settings, and the actual connection path shown in the logs.

Check local ports and the system proxy

A common setup uses 7890 for the mixed-port and 9090 for the external controller port, but these are common defaults, not requirements. If another process occupies 7890, the system proxy may still point to the old port, causing browsers and subscription updaters to fail. First confirm the current HTTP, SOCKS, and mixed ports under the client’s “General” or “Network” page, then verify that the operating system’s proxy address matches.

TUN mode usually covers more traffic than the system proxy, but enabling TUN cannot fix an expired link, an incorrect UA, or invalid YAML. If updates fail only when TUN is enabled, temporarily disable TUN while keeping the system proxy on and test again. Then check DNS hijacking, route exclusions, and whether the subscription domain is being sent to an unavailable proxy group.

How to set the automatic update interval

More frequent updates are not always better. For subscriptions whose nodes and policies change infrequently, every 6 hours is usually enough: 21600 seconds. For rapidly changing subscriptions where the server permits frequent requests, use 1 hour, or 3600 seconds. Daily updates equal 86400 seconds. Intervals below 15 minutes create unnecessary requests and may trigger HTTP 429 rate limiting.

Graphical clients usually provide an update interval in the subscription editor; the unit may be hours, minutes, or seconds. Read the field description before editing, and do not enter 3600 in a field measured in hours. Some clients count time only while the application is running; after the device sleeps, the next update may run immediately upon wake.

mihomo proxy-provider update example

If the configuration uses proxy-providers, you can set an independent interval for each provider. The value is measured in seconds. The example below fetches each provider file every 6 hours and runs a health check every 10 minutes. Health checks and subscription updates use separate timers and cannot replace each other.

proxy-providers:
  service-a:
    type: http
    url: "https://sub.example.com/provider/demo-token"
    path: ./providers/service-a.yaml
    interval: 21600
    health-check:
      enable: true
      url: "https://www.gstatic.com/generate_204"
      interval: 600

interval: 21600 controls how often the remote provider file is refreshed; health-check.interval: 600 controls only node availability checks. Setting the health check to 600 seconds does not make the subscription download every 10 minutes. Conversely, a successful subscription update does not prove that every node passed the health check.

Complete the troubleshooting process in order

Handle subscription failures from the outside in: confirm the link and server response first, then check request headers and the network path, and finally address format and local loading. This prevents repeated DNS, TUN, and rule changes when the link itself is already invalid.

1. Record the error time.Run one manual update, then immediately check the log for the status code, domain, timeout, or parsing error.
2. Confirm the link is complete.Copy a Clash or mihomo link again from the server and create a temporary subscription in the client.
3. Test the direct response.Disable “Update through proxy,” try once, and record the result.
4. Test the proxy response.Restore a known-working node, enable “Update through proxy,” and try again.
5. Verify the User-Agent.Use only an identifier explicitly supported by the server, then compare the 403 response, 200 response, and response body.
6. Check the content format.Confirm that the response is not HTML, error JSON, an empty file, or an incompatible Base64 list.
7. Check the core and fields.Review the mihomo or Clash core version and look for unknown fields, proxy-group references, and YAML indentation problems.
8. Reload the configuration.Confirm that the new file was saved successfully and explicitly select the updated entry on the configuration page.
9. Restore a reasonable interval.Use 6 hours for ordinary scenarios and 1 hour when changes are frequent, then watch for HTTP 429 responses.

Verify the update succeeded

After the update finishes, do not rely only on the green success message. Record the total node count and proxy-group names, then run a latency test on one node. Next, visit a page suitable for verifying the egress address and confirm in Clash’s connection log that the request matched the expected policy. If the client reports success but the node list and file modification time are unchanged, check whether an inactive subscription entry was updated instead.

If automatic updates occasionally fail while manual updates succeed immediately, common causes include the device just waking from sleep, the network not being ready, the proxy core starting after the subscription task, or brief server-side rate limiting. Consider extending the update interval and keep the failure logs. If updates fail every time on the same network, compare direct access, the system proxy, and TUN paths instead of shortening the refresh interval further.

A stable setup should meet four conditions: the subscription link is valid, the update route is clear, the response is compatible with the current core, and the refresh frequency complies with the server’s limits. Confirming these separately usually isolates the failure to a specific layer without reinstalling the client or clearing the entire configuration.