Clash Subscription Update Failures: Troubleshooting Causes and Setting Automatic Update Intervals

First identify where the failure occurs

An “update failed” message in a Clash client does not point to a single problem. A remote subscription update typically passes through DNS resolution, TCP and TLS connections, the HTTP request, content download, configuration parsing, core validation, and configuration switching. When the interface shows only a generic failure notice, first determine which step stopped instead of repeatedly clicking Update.

The most useful clues are the client log, HTTP status code, and downloaded content. Note the failure time, open the log page, and look in the same minute for entries containing the subscription domain, timeout, certificate, 401, 403, 404, parse, or yaml. Each stage calls for a different response.

Expired links, blocked requests, and abnormal server responses

Make sure the link was not damaged when copied

A subscription URL can break because of line wraps, trailing spaces, truncation by chat apps, or HTML escaping. A common symptom is that only the part before the first & was copied, or that the final token is missing several characters. Recopy the complete URL from the subscription service’s management page and replace the old address in the client; do not assemble the token by hand.

HTTP status codes can quickly narrow down the cause. 401 usually means the credentials or token is no longer valid; 403 may be related to access policies, rate limits, or the source network; 404 means the path does not exist; 410 is commonly used to indicate that a resource has been permanently retired; 429 means too many requests were sent in a short period. Repeatedly refreshing after a 429 usually only extends the restriction.

Test the HTTP request separately in a terminal

On desktop systems, use curl to test network downloading separately from client-side parsing. First save the subscription URL in an environment variable in the current terminal, then run the command below. It sets a 10-second connection timeout, a 30-second total timeout, and follows HTTP redirects.

export SUB_URL='complete subscription URL'
curl -L \
  --connect-timeout 10 \
  --max-time 30 \
  -D response-headers.txt \
  -o profile.yaml \
  "$SUB_URL"

Check the final status code in response-headers.txt, then inspect the beginning of profile.yaml. A standard Clash or Mihomo configuration typically contains YAML fields such as proxies:, proxy-groups:, and rules:. If the content starts with <html, the download is actually a login page, verification page, or error page. A JSON error object cannot be imported directly as a configuration either.

Some services return a Base64-encoded universal subscription, while the client entry point accepts only Clash YAML. In that case, the network request succeeds but parsing still fails. Select the Clash, Clash Meta, or Mihomo format on the service side instead of merely changing the file extension.

Check the system clock and TLS connection

An inaccurate device clock can affect HTTPS certificate validation. If the log shows certificate has expired, not yet valid, or a handshake failure, first enable automatic time synchronization. In Windows, open Settings → Time & language → Date & time and enable automatic time setting. On macOS, open System Settings → General → Date & Time and enable automatic date and time.

If a browser can open the subscription URL but the client consistently times out, compare the network paths used by both. The browser may be using the system proxy while the client updater uses a direct connection, or the reverse may be true. This difference is a common reason why a browser works while Clash updates fail.

Troubleshoot proxy loops, TUN mode, and DNS paths

A subscription update request needs a usable startup path. If the updater depends on the current proxy while every node in the active configuration is down, a startup dependency forms: the nodes must be updated before they can recover, but the update request must pass through those same nodes. Another loop occurs when requests from the client process are sent back to the client through the system proxy or TUN. Logs may show repeated connections to the same domain, connection refusals, or timeouts.

Break the startup dependency with a direct-connection test

1. Record the current configuration and mode, then temporarily disable TUN mode.
2. Disable the system proxy and confirm that a browser or terminal can access ordinary websites directly.
3. Run one manual update for the target subscription in the client.
4. After the update succeeds, re-enable the system proxy or TUN and restore the original rule mode.

If the subscription domain is reachable only through a proxy, keep a known-good startup route available. Switch to a local configuration that still connects, then update the remote configuration. Do not delete the last working configuration before testing the remote subscription.

Check local ports and the system proxy

Common desktop configurations use 7890 as the HTTP or mixed listening port. Older split configurations may use HTTP 7890 and SOCKS 7891, while the external controller port is often 9090. These values can be changed, so use the actual values shown on the client’s Settings or Ports page.

If the system proxy points to 127.0.0.1:7890 but the core is not running, or mixed-port has been changed, every update request sent through the system proxy will fail. First confirm that the core is running, then check that the port is listening. Port conflicts commonly appear in logs as address already in use.

Verify the subscription domain’s DNS results

With TUN and fake-ip enabled, applications may see addresses from the fake-ip pool; this is normal forwarding behavior. The client’s own updater must still resolve the real domain. If the log shows DNS timeouts, temporarily disable TUN and test again to distinguish the system DNS path from the Mihomo DNS path.

Also check IPv6. Some networks return AAAA records but do not have a stable IPv6 route, causing a 10- to 30-second wait before timing out. Temporarily disable IPv6 for the network interface at the system level, or adjust the client’s DNS and connection settings before testing again. Make permanent changes only when the test clearly points to IPv6, so other problems are not hidden.

What to do when downloading succeeds but parsing fails

Once the log shows HTTP 200, shift the investigation from networking to content. First check whether the downloaded file is the expected configuration, then check YAML syntax, and finally verify that the fields are supported by the current core. Mixing these stages often leads to repeated DNS and proxy changes without addressing the parsing error.

Validate the basic YAML structure first

YAML is indentation-sensitive. Tab characters, incorrect list nesting, and unclosed quotes can all cause a configuration to be rejected. With the Mihomo command line, you can test a configuration without starting a proxy listener:

mihomo -t -f profile.yaml

A successful test usually reports that configuration validation passed; a failure identifies the field or line number. If the configuration is generated automatically by a remote subscription, avoid patching a local file that will be overwritten on the next update. Fix the subscription format or conversion rules instead.

Distinguish a complete configuration from a proxy provider

A complete remote configuration usually includes ports, DNS, proxy groups, and rules and can be enabled directly in the client. proxy-providers references a separate collection of nodes from the main configuration, so the two use different update mechanisms. Importing a provider file containing only a node list as a complete configuration may leave out proxy-groups and rules; conversely, using a complete configuration as a provider URL will fail because its structure does not match.

In a Mihomo configuration, the provider interval is measured in seconds. For example, 21600 means checking once every 6 hours. It controls only that provider and is not the same as the update interval for the entire remote configuration set in a graphical client.

proxy-providers:
  remote-nodes:
    type: http
    url: "https://example.net/subscription/token-value"
    path: ./providers/remote-nodes.yaml
    interval: 21600
    health-check:
      enable: true
      url: "https://www.gstatic.com/generate_204"
      interval: 600

Field compatibility depends on the core version

A subscription service may add Mihomo fields while the client still uses an older core. It may also output legacy Clash fields that do not match the current strict validation rules. First check the actual Mihomo version on the client’s About or Core page, then inspect the field identified in the parsing log. Updating the graphical interface does not necessarily update the core, so verify the core version again afterward.

If an old configuration still loads but every new configuration has failed since a particular day, first compare whether the server-side generated format changed. If one node causes the entire configuration to fail, use the log to identify its protocol and fields, then have the subscription service generate a compatible format again.

How to set automatic update intervals in each client

Different clients use slightly different labels for “automatic updates.” The paths below reflect common interfaces in Clash Verge Rev 2.3.x, Clash Meta for Android 2.11.x, and FlClash 0.8.x. Buttons may move in minor releases, but the setting should apply to the remote configuration itself, not to node health checks.

Recommended for everyday use: 12 to 24 hours

When nodes and rules do not change often, 1,440 minutes is enough for routine updates and reduces requests to the service. If the provider changes nodes several times a day, use 720 minutes. Choose 360 minutes only when faster synchronization is clearly needed; intervals of 5 or 10 minutes are usually unnecessary and may trigger HTTP 429.

Mobile updates are also affected by the operating system’s background policies. Android battery restrictions may pause background tasks, and iOS does not guarantee that a client will run on schedule after it is closed. “Set to 12 hours” means the client checks at that interval when the system gives it an opportunity to run; it does not mean the system will wake the app at the exact time. For important updates, open the client in the foreground and run one manually.

Do not confuse subscription updates with health checks

Subscription updates download nodes, proxy groups, and rules. Health checks send requests to a test URL to determine whether existing nodes are reachable. Setting health checks to 600 seconds does not download the subscription every 10 minutes. Conversely, updating the subscription once a day does not prevent nodes from being tested every 10 minutes.

For a provider with 100 nodes, an overly short health-check interval can generate a large number of concurrent requests. Start with 600 or 900 seconds and adjust it based on device power use and node count. The latency-test URL should return a lightweight response and represent actual outbound connectivity.

The correct steps for a forced manual update

The goal of a forced update is to obtain a new configuration and confirm that it has been loaded, not merely to watch a progress spinner. The sequence below also avoids concurrent requests, misleading cache results, and interference from old connections.

1. Open the client log and record the current configuration name, update time, and core status.
2. Stop any duplicate updates in progress and click the Update button for the target configuration once.
3. Wait for the request to finish and confirm the final HTTP status and parsing result in the log.
4. Check whether the update time on the configuration card changed and whether the node count or proxy groups match expectations.
5. Select the new configuration explicitly, then reload the configuration or restart the core.
6. Select the proxy-group node again, close the application connection being tested, and reopen it.
7. Open a connection-testing page or inspect the connection log to confirm that the new connection matched the expected rule and outbound route.

If the update succeeds but the node list does not change, first compare whether the server-side content actually changed. HTTP caching may return 304 Not Modified, meaning the client’s current version is still considered valid—not that the network failed. If the server has changed but the client keeps using old content, delete the remote configuration and import it again. Save local overrides, proxy-group selections, and custom rules first.

Switching configurations does not automatically migrate every existing TCP or UDP session. Browser keep-alive connections, downloads, and instant-messaging sessions may continue using the original route. During verification, close the relevant application connection and restart the app if necessary instead of merely refreshing the same long-lived connection.

What diagnostic information to keep if it still fails

If the update still fails after these checks, prepare a minimal diagnostic record: client name and version, Mihomo core version, operating system version, failure time, HTTP status code, 10 log lines before and after the error, whether TUN is enabled, the system proxy address, listening ports, and test results for both direct and proxied routes.

Keep only the domain in the subscription URL; redact the token and query parameters. Check the configuration file for authentication details as well. If the problem occurs only on a particular network, include comparison results from home broadband, mobile data, or a corporate network. If switching networks fixes it immediately, focus on DNS, IPv6, access policies, and the local gateway rather than repeatedly reinstalling the client.

The complete diagnostic sequence is: identify the stage from the log, test URL reachability, inspect the returned content and YAML, then address core compatibility, automatic update intervals, and configuration reloads. This separates “subscription expired,” “download failed,” “parsing failed,” and “configuration not switched” into distinct problems and reduces unrelated changes.