Clash Subscription Update Failed: Common Errors and Auto-Update Intervals

First pinpoint the failure: download, parsing, or activation

Subscription updates usually involve three steps: the client requests the subscription URL, checks the response, then saves or loads the configuration. An “update failed” message does not necessarily mean the nodes are down; working nodes do not guarantee the subscription URL is still valid. Keep your current working configuration while troubleshooting. Don’t delete and re-import it, and avoid repeatedly hitting refresh.

1. Identify what failed: Is it the full remote configuration under “Profiles,” or a specific node collection under “Proxy Providers”?
2. Capture the exact error: Open “Logs” in the client, run one manual update, and save the errors, HTTP status code, and configuration name from around that time. Menu names vary between clients.
3. Check the current state: Confirm whether the old configuration still works, whether the last successful update time changed, and whether the intended configuration remains selected.

Download timeout: check the domain, network, and request path separately

Try another network before changing the configuration

context deadline exceeded means the operation timed out, but that alone doesn’t tell you whether DNS, the TCP connection, the TLS handshake, or response reading was slow. Check the specific stage in the logs first. Then switch the same device from Wi-Fi to a mobile hotspot and manually update once using the same subscription URL. Change one factor at a time to see whether the original network is the cause.

• Domain lookup failed: Check for spaces, line breaks, or missing characters in the URL. Being able to open other websites doesn’t prove that the subscription domain resolves correctly.
• Connection refused: connection refused usually means the destination port rejected the connection. Check the server address or whether the local proxy is listening.
• Read timed out: The server may have accepted the connection but failed to complete its response. Note when it happened and which network you were using, then contact your provider.

System proxy, TUN, and subscription downloads are separate

The client’s UI process may download the full configuration, while another component may handle it. Remote resources under proxy-providers are usually fetched by the core. So a browser using the proxy doesn’t prove that subscription requests take the same route. Which connections TUN can intercept also depends on routing, process exclusions, and the client implementation.

If the client offers an option such as “Update through proxy,” first make sure a working node is available, then toggle the option and compare. If all existing nodes are down, requiring one to download a new subscription can create a dependency loop. Try a direct connection or a network that can reach the subscription URL instead.

Certificate errors: check the clock and trust chain first

HTTPS subscriptions require the server’s identity to be verified. Read the full certificate error before taking action; don’t simply disable verification. skip-cert-verify in a node configuration affects TLS verification for that proxy node. It is not a general fix for the client’s subscription downloader.

1. Sync the system clock: Enable automatic date and time in your operating system, then check the year, time zone, and sync status. An incorrect clock can make a valid certificate appear not yet valid or expired.
2. Check the domain: Errors such as certificate is valid for often indicate a hostname mismatch. Don’t replace the subscription domain with an IP address; doing so can break both certificate verification and virtual host selection.
3. Rule out network sign-in: Public Wi-Fi may require you to open a sign-in page first. Log in, then try updating again. HTTPS inspection on a workplace network can also alter the certificate chain; check with your network administrator.
4. Check the trust environment: certificate signed by unknown authority may mean the server’s certificate chain is incomplete, or that the device’s trust store or network is interfering. Testing on a personal hotspot can help narrow it down.

If the device clock is correct and the same subscription domain reports an expired certificate on multiple networks, ask your provider to fix it. Don’t change the HTTPS URL to HTTP or bypass the warning by installing an unfamiliar root certificate.

Invalid YAML response: check the status code and subscription type

A successful HTTP request doesn’t guarantee a usable configuration. Even with a 200 status, the response body may be a sign-in page, an access verification page, or an account expiration notice. Conversely, a Content-Type of text/plain doesn’t automatically mean the response is invalid; some services use it for valid YAML. Check the body structure to be sure.

How to handle common responses

• Body starts with <!DOCTYPE html>: You received a web page. Make sure you copied the client subscription URL, not the account dashboard URL. Don’t save the page as a configuration and try to force-load it.
• Body contains links such as vmess:// or a long string of encoded text: You may have selected a generic node subscription instead of a configuration format supported by your client. Return to the provider’s subscription export page and choose the appropriate type.
• Body contains a JSON error: Read the server’s error message first. Changing YAML indentation won’t fix an expired account or invalid token.
• Body is valid YAML: Check the field hierarchy, data types, and core compatibility next. Valid YAML syntax doesn’t guarantee that the structure is supported by Clash or mihomo.

Don’t mix up full configurations and node collections

A full configuration can include proxies, proxy-groups, and rules, and can also reference node collections through proxy-providers. A typical provider YAML lists nodes under proxies:; it is not a complete configuration with policy groups and rules. Using a full configuration URL in a field that accepts only a node collection—or importing a node collection as a full configuration—can cause parsing or runtime errors.

If the logs explicitly say a node type or field isn’t supported, check the core name and version on the client’s About page. Traditional Clash and Clash Meta (now called mihomo) support different features; the app’s name alone doesn’t tell you which core it uses. For field structure, see the configuration file structure guide. For format conversion limits, see the subscription conversion guide.

Auto-update intervals: three different meanings of interval

“Update subscriptions every hour” doesn’t mean adding interval: 3600 anywhere in the YAML. Scheduled refreshes for a full remote configuration are usually managed by the client’s profile settings. Provider downloads and node health checks use their own fields. Confusing the three can leave latency tests running while the node list stays unchanged.

Full subscription: set it on the remote profile

A common path is “Profiles” → the target remote profile’s menu → “Edit” → Auto Update or Update Interval. The exact labels depend on the client. If the field uses minutes, enter 60 for one hour; if it uses seconds, enter 3600. Don’t assume the same number works across clients.

As a starting point, try updating every 6 hours or once a day, then adjust to your provider’s requirements. Frequent refreshes usually don’t help if the subscription URL is stable and the nodes rarely change. Don’t assume that entering 0 disables updates; use an explicit off switch if available and check the client’s documentation.

HTTP provider: set the interval on the provider

Here’s an example mihomo HTTP provider snippet, not a complete runnable configuration. example.com is a documentation-only domain and won’t provide working nodes. Replace it with the node collection URL from your account, and have the policy group reference the collection name with use.

proxy-providers:
  daily-nodes:
    type: http
    url: "https://example.com/subscription.yaml"
    path: ./providers/daily-nodes.yaml
    interval: 21600
    health-check:
      enable: true
      url: "https://www.gstatic.com/generate_204"
      interval: 300

Here, 21600 seconds is 6 hours and controls how often the node collection is downloaded. 300 seconds is the health-check interval; it won’t refresh the node list. The health-check URL must also be reachable through the current node. Use a different cache file path for each provider to avoid writing to the same file.

Manual refresh: test the fix and confirm the result

Manual refreshes are useful for checking whether a fix worked, not for repeated trial and error. In particular, stop clicking if you get a 429. If the response includes Retry-After, wait for the time specified by the server. For server errors such as 500, 502, or 503, keep the old configuration and retry later or check the service status.

1. Keep a backup: Use the client’s export feature to save the current working configuration. Record local overrides, policy selections, and the subscription source separately.
2. Select the right target: Update the remote profile itself; don’t mistake a policy group’s latency test button for a refresh button. When updating a provider, verify the collection name too.
3. Change one thing: For example, switch networks or correct the system clock, then refresh once and note whether the error changed.
4. Check that it saved and loaded: Confirm the update time changed, the logs show no subsequent parsing errors, and the intended configuration is active. Some clients don’t switch automatically after updating a profile that isn’t currently selected.
5. Test the actual connection: Make sure the policy group still selects a working node, then visit a service you normally use. A successful download and working access to your services are two separate checks.

If the nodes work again after an update but your custom rules are gone, check whether you edited the remote configuration directly. A later download may overwrite that file. Put long-term rules in an override, merge, or extension feature explicitly supported by the client, and verify the resulting configuration. See the subscription import tutorial for import and switching steps.

When reporting an issue to your provider or client maintainer, include when it happened, your OS and client versions, core version, redacted status code, and whether the same URL works on another network. This helps more than simply reporting “update failed.” Remove subscription tokens, full node credentials, and sensitive information from account screenshots before sharing them.