Clash subscription update failure: common causes and auto-update interval settings

First Identify Where the Failure Occurs

When a Clash client updates a subscription, it first connects to the subscription URL, receives the server response, and parses it into a configuration file. Only then does it load proxy nodes, rules, and DNS settings. The same “update failed” message may indicate a connection timeout, an unexpected HTTP status, invalid response content, or a YAML parsing error.

Do not delete the current configuration first. Keep a working copy, then review the update message and runtime logs. Some clients show download errors beside the subscription card, while others record the full reason only in the logs. Common paths are “Subscriptions” → “Config card” → “Update”; logs are usually under “Settings” → “Logs” or “Logs” → “Core logs.”

Step-by-Step Checks for Subscription Timeouts

Step 1: Check Whether the Subscription Domain Is Reachable

A timeout does not necessarily mean the nodes are down. Subscription downloads and proxy connections use two separate paths: the first reaches the subscription service domain, while the second connects to a proxy server in the configuration. Even if an existing node can open websites, DNS, routing, or server problems may still prevent access to the subscription domain.

1. Record when the failure occurs, then run two manual updates 60 seconds apart to rule out a brief network fluctuation.
2. Switch networks once—for example, move from home broadband to a mobile hotspot—and try the update again.
3. Test both states separately: with the system proxy disabled and with the current proxy enabled. Some subscription domains require a direct connection, while other networks can reach them only through an existing proxy.
4. Check the device date, time, and time zone. A significant clock difference can terminate the TLS connection before the download begins.
5. Review the target domain and failure stage in the logs. A DNS lookup timeout and a TCP connection timeout require different fixes.

If the update works with the system proxy disabled, check whether the subscription domain was incorrectly routed through an unavailable node. Add a direct rule for that domain or temporarily select DIRECT during the update. If updates work only with the proxy enabled, keep a stable configuration as the update path and do not overwrite it until the new configuration has been verified.

Step 2: Distinguish DNS Timeouts from Connection Timeouts

When the logs show “no such host,” “DNS lookup failed,” or “i/o timeout” and point to DNS, check Clash’s DNS module first. With the mihomo core, also review the roles of nameserver, proxy-server-nameserver, and nameserver-policy. If the proxy server’s domain cannot be resolved, both subscription downloads and node connections may be affected.

• Temporarily disable TUN mode and retry to determine whether traffic is looping between TUN, the system proxy, and local DNS.
• Make sure local listening ports are not conflicting. The common mixed-port is 7890; HTTP commonly uses 7890 and SOCKS commonly uses 7891. Use the values in the current configuration as the authority.
• If a packet capture tool, another proxy client, or a VPN is running at the same time, fully quit one of them first, then restart the Clash core.
• After changing DNS settings, restart the core once. Switching proxy groups alone usually does not rebuild all DNS state.

Step 3: Adjust the Download Timeout Carefully

If the client offers a subscription timeout setting, temporarily raise it from 10 to 30 seconds for testing. If failures continue beyond 30 seconds, increasing it to several minutes usually will not fix a broken path. A reasonable test is a 10-second connection timeout, a 30-second total download timeout, and support for following HTTP redirects.

On desktop systems, use a command to inspect the response status. First run read -s SUB_URL in a terminal and paste the subscription URL. Press Enter, then run the commands below. This reduces the chance of leaving the token directly in shell history.

curl -L \
  --connect-timeout 10 \
  --max-time 30 \
  -D headers.txt \
  -o profile.yaml \
  "$SUB_URL"

wc -c profile.yaml
head -n 8 headers.txt

An exit code of 0 only means the download completed; it does not prove the content is a Clash configuration. Check the HTTP status, file size, and content type as well. A valid configuration will usually contain some of proxies, proxy-providers, proxy-groups, or rules.

What to Do About 404, 401, or 403 Responses

404: The URL Path or Subscription Token Has Changed

A 404 means the server is reachable, but the current path does not exist. Common causes include missing query parameters, a reset subscription token, a retired URL, or special characters truncated by a chat app. Do not compare only the domain; compare the complete URL from the protocol prefix to the final character.

1. Return to the subscription service dashboard and copy a subscription URL for Clash or Clash Meta again.
2. Delete the failed entry in the client and paste the URL again to prevent the old entry from using a cached address.
3. Make sure there are no spaces, line breaks, or typographic quotation marks before or after the URL.
4. If the service recently reset the token, treat the old URL as invalid and update it on every device.
5. Wait 2 to 5 minutes and try again. Some services need time to regenerate the configuration or synchronize edge caches.

Seeing a download in a browser does not guarantee that the client will succeed. Some services return different formats based on the User-Agent or require specific request headers. Conversely, a web page in the browser does not prove that the subscription is invalid: the server may redirect ordinary browser requests to a help page. Use the status code and actual response content in the client logs as the source of truth.

401 and 403: Authentication or Access Policy Denied

A 401 usually means the token is invalid or missing. A 403 may indicate that the account status, source address, request rate, or server policy blocks the request. Sign in to the service dashboard to confirm the account and subscription status, then generate a new URL. If you click update dozens of times in a short period, the server may apply rate limiting; stop requests for 10 to 30 minutes.

Downloaded Successfully but Empty or Unparseable

First Check Whether the Response Is YAML, Base64, or HTML

A client can still fail after receiving HTTP 200. The server may return a login page, an error message, an empty file, a generic Base64 node list, or fields unsupported by the current client. If the downloaded file is only a few dozen bytes, or begins with <!DOCTYPE html> or <html>, it is not a configuration file.

Clash configurations typically use YAML. Nodes can be written directly under proxies or loaded from a remote provider through proxy-providers. Text containing only links in another client’s format cannot be loaded directly as a complete Clash configuration. If the service dashboard offers a client type selector, choose the Clash or mihomo format that matches the core.

Check YAML Indentation and Field Types

YAML uses spaces for nesting; tabs must not be mixed into the same indentation level. Common errors include a nonnumeric port, a proxy group referencing a missing node, a rule provider without behavior, or fields unsupported by an older core. Update the client and mihomo core, then load the configuration again to rule out compatibility issues caused by an outdated version.

proxy-providers:
  remote-main:
    type: http
    url: "https://sub.example.net/client/REDACTED"
    path: ./providers/remote-main.yaml
    interval: 21600
    health-check:
      enable: true
      interval: 600
      url: "https://www.gstatic.com/generate_204"

In the example above, interval: 21600 means the provider updates every 21,600 seconds, or 6 hours. The health check’s interval: 600 means node availability is tested every 10 minutes. They serve different purposes: health checks do not redownload subscriptions, and subscription updates do not replace ongoing node checks.

Update Succeeded but the Node Count Is Zero

When the node count is zero, inspect the raw response first to confirm that the server actually returned proxy entries. An expired account, exhausted traffic, empty regional filtering results, or an incorrect conversion template can all produce a structurally valid configuration with no nodes. If the configuration contains only rules and proxy groups, without proxies or usable proxy-providers, the client cannot create nodes on its own.

Also verify the proxy group references. A configuration may contain nodes, yet the interface can show empty groups when a group’s use points to the wrong provider name. Names are case-sensitive: remote-main and Remote-Main are different identifiers.

How Long Should the Auto-Update Interval Be?

More frequent updates are not always better. Subscription content usually does not change minute by minute; frequent requests add server load and can trigger rate limits. For personal devices, 6 to 24 hours is a more stable range. When waiting for a server-side fix, run one manual update instead of changing the interval to 60 seconds.

Where to Find the Setting in GUI Clients

Clients do not use consistent names for “configuration” and “subscription.” Common paths include “Subscriptions” → “Select configuration” → “Edit” → “Update interval” or “Configuration” → “Subscription card menu” → “Auto-update.” Some clients use hours, so 6 means 6 hours; others use minutes, so 6 hours means entering 360. Always check the unit shown beside the input field before saving.

mihomo GUI clients such as Clash Verge Rev usually manage remote configurations on the “Subscriptions” page. After changing the interval, save the subscription settings, run one manual update, and check the update time. Older versions of Clash for Windows use different menu names; check the remote configuration entry and its update options on the Profiles page. If the interface has no interval setting, do not assume that background updates are enabled.

The Two interval Settings in mihomo Configuration

When writing a configuration by hand, the provider update interval and health-check interval are easiest to confuse. The top-level interval under a proxy-providers entry controls when the remote file is downloaded again; the interval nested under health-check controls connectivity tests. The first is typically 21,600 to 86,400 seconds, while the second is commonly 300 to 900 seconds.

Overly frequent health checks create extra connections. With many nodes, testing every 30 seconds can cause bursts of concurrency and drain the battery. On mobile devices, set health checks to 600 seconds or longer and enable them only for providers actually in use. Changing the health-check interval will not fix a subscription download failure.

How TUN Mode, the System Proxy, and Subscription Updates Interact

With TUN enabled, the client can take over more system traffic, but subscription requests may still be sent by the GUI process or the core. Implementations differ between clients, so requests do not necessarily follow the current proxy group. When “the browser works but the client’s update times out,” check whether the GUI process uses the system proxy, whether the subscription domain matches a rule, and whether TUN routing is looping.

• Disable TUN while keeping the system proxy enabled, then test one update.
• Disable the system proxy while keeping only TUN enabled, then test one update.
• Disable both and test one update with the subscription request going direct.
• Restore the original settings, restart the core, and confirm that the logs show no port conflict or route installation failure.

Change only one variable per test above. If DNS, proxy mode, TUN, and the subscription URL are all changed at once, recovery will not reveal the true cause. During testing, you can keep rule mode enabled and set the subscription domain to DIRECT or route it through a stable proxy group.

A Repeatable Troubleshooting Sequence

1. Keep the old configuration: Export the working configuration first; do not overwrite it.
2. Read the full error: Record the status code, target domain, time, and key log terms.
3. Check the URL: Copy the subscription URL again and rule out spaces, truncation, and expired tokens.
4. Switch networks: Test on both the current network and a mobile hotspot.
5. Switch the request path: Test direct access, the system proxy, and TUN in sequence.
6. Inspect the response: Confirm the HTTP status, file size, and whether the content is YAML.
7. Validate the configuration: Check proxies, proxy-providers, proxy group references, and YAML indentation.
8. Check the core: Update to a mihomo core version supported by the client, then load the configuration again.
9. Set a sensible interval: Use 6, 12, or 24 hours for everyday use and avoid minute-level updates.
10. Contact the service last: Provide the failure time, status code, and redacted logs; never send the full subscription token.

What to Check After Updates Resume

After the subscription reports a successful update, confirm the update time, node count, and proxy groups before switching to the new configuration. Test latency on one node, then visit commonly used sites to verify rule routing. If nodes exist but every connection fails, the problem has moved from “subscription download” to “node connection”; inspect connection logs instead of repeatedly updating the subscription.

Finally, restore a sensible auto-update interval. Cancel any short interval used during troubleshooting to avoid continuous background requests. On desktop, check whether one update occurs as scheduled within 24 hours; mobile operating systems may restrict background tasks, so update times can be affected by battery-saving policies and system scheduling. If necessary, update manually after opening the client.

The complete decision path is: the URL is valid, the network is reachable, the response content is correct, the configuration parses, proxy group references are valid, and the nodes connect. Confirming these six layers is more effective than repeatedly reinstalling the client or clicking Update over and over.