Clash subscription update failed? Fix parse errors, expired links & User-Agent issues

First, tell request failures from configuration parse errors

A Clash subscription update usually involves three steps: the client requests the subscription URL, reads the response, then passes it to the configuration handler and core for validation. A failure at any stage may show up as “Update failed.” So before reinstalling, open the subscription details and logs, and note the full error, when it occurred, and which core is in use.

The same subscription URL can return different content in a browser, client, or command line. Opening it in a browser only confirms that the request received a response; it does not mean the response is a usable Clash configuration. Existing nodes may still connect because the old configuration works, but that does not mean the subscription endpoint is healthy.

Expired links, account issues, and HTTP status codes

Copy the current subscription URL again

Sign in to your subscription provider and check your plan status, expiration date, and remaining data. Then copy the current URL intended for Clash or mihomo. An expired plan, reset token, migrated endpoint, or exhausted data allowance can all affect the response. The provider determines how these conditions are handled, so a single status code does not prove that an account has expired.

• Check the beginning and end of the URL as you copy it. Avoid adding line breaks, spaces, quotation marks, or punctuation from a chat app.
• Keep the entire query string. Do not remove anything after the question mark to “simplify” the URL.
• If you copied the address from a webpage's source, note that & is the HTML representation; the actual URL uses & between parameters.
• If you recently reset your subscription token, the old URL may stop working immediately. Update the existing subscription entry instead of adding multiple configurations with the same name.

Respond to the status code instead of repeatedly clicking Update

401 commonly means authentication is missing or invalid. 403 can also result from access restrictions, risk controls, or request-header policies. A 404 may indicate that the endpoint path has changed. For 429, wait for the duration specified by Retry-After. If no guidance is provided, pause automatic updates and contact the provider. Repeated retries increase request volume; they will not fix an invalid token.

For 500, 502, or 503, check the server or gateway status. Note when the error occurred and try again later. A 304 may be a normal cache validation response, not inherently a failure; check whether the client retained the previous content correctly.

Request timed out? Check the network route used to download the subscription

System proxy settings, TUN mode, and subscription downloads are related but separate. Some clients download configurations themselves; others offer a “Update through proxy” option. The core's proxy providers may also have their own update settings. If an update fails in the client, do not assume it used the same route as your browser.

1. On the same network, capture a failure log and identify whether it was a DNS lookup failure, TCP connection failure, TLS error, or read timeout.
2. Check which local proxy port the client is actually listening on; do not copy one from an outdated guide. The command in this article uses 127.0.0.1:7890, which applies only if that port is an HTTP or mixed-proxy listener.
3. Keep a working copy of the old configuration and test direct and proxied requests separately. Change only one condition at a time.
4. If switching networks fixes the problem, investigate DNS, gateway restrictions, and security software on the original network instead of changing node passwords.

Compare the response with curl

The commands below are for Bash on Linux or macOS. The URL is read without echoing it, so it is not written directly to shell history; still, keep your device secure while entering it. The examples allow 10 seconds to connect and 30 seconds for the full request, and save the response headers and body to separate local files. On Windows, you can use curl.exe, but adjust the variable input syntax for your terminal.

read -r -s -p 'Subscription URL: ' SUB_URL
printf '\n'

curl --noproxy '*' --connect-timeout 10 --max-time 30 \
  -D subscription.headers -o subscription.body "$SUB_URL"

curl --noproxy '' --proxy http://127.0.0.1:7890 \
  --connect-timeout 10 --max-time 30 \
  -D subscription-proxy.headers -o subscription-proxy.body "$SUB_URL"

unset SUB_URL

“Direct” here means curl is not using an explicit proxy; if TUN is enabled at the system level, it may still capture the connection. To compare routes, temporarily disable TUN only if doing so will not disrupt other tasks, then repeat the test. For 301 or 302, check the domain in Location and verify that it is trusted before following the redirect with -L.

User-Agent: Why the same URL can return different formats

User-Agent is an HTTP request header that identifies the requesting software. Some subscription services use it to choose a response format—for example, returning a help page to a browser, YAML to a specific client, or an error to an unrecognized request. Others ignore this header and use a dedicated URL or query parameter instead.

Check the provider's requirements before changing request headers

1. Check the provider's format guide to confirm whether the URL is for Clash, Clash Meta (mihomo), or another client.
2. Note the client name and version, as well as the core version. These are separate versions, and updating the client does not necessarily update its core.
3. Compare the client log with the command-line response. Do not mistake a browser login page for subscription content.
4. Only enter a specific User-Agent in the client's subscription request settings if the provider explicitly requires it. Menu names vary by client.

For example, if the provider explicitly requires clash.meta, add -A 'clash.meta' to the curl request above for comparison. This is a value that some services may accept—not a standard request header for all mihomo clients or a universal fix. Faking a request header cannot bypass an expired account or missing permissions.

Do not add User-Agent at the top level of a configuration and expect it to change the client's subscription requests. Downloading a full configuration and having the core update proxy-providers are separate processes; only settings supported by the relevant component will take effect. If changing the header returns YAML but the client still fails, check the format and core compatibility next.

HTTP 200 but parsing still fails? Inspect the response body

200 OK means the HTTP request succeeded; it does not mean the content is suitable for Clash. The response might be a login page, CAPTCHA, JSON error, Base64-encoded node list, or configuration for a different core. Check the Content-Type response header, then inspect the beginning of the body locally. Headers can be inaccurate, so the content itself is what matters.

A full configuration and a proxy-provider file are not interchangeable

A full configuration usually defines proxy groups, rules, and runtime options. A remote proxy-providers file mainly supplies a list of nodes. Putting a full configuration into a provider URL that expects only a node list—or using a node list as a full configuration—can cause parse errors or leave policies missing. rule-providers supply rule sets; they are not subscription URLs for nodes.

Clash Meta was later renamed mihomo, and its protocol and configuration support does not exactly match the original Clash. Nodes such as Hysteria2 and VLESS require a compatible core. If the log reports an unsupported type or field, first confirm which core is actually running, then choose an output format supported by your provider. Changing the type name does not convert one protocol into another.

YAML indentation and configuration reference errors

If you see yaml: line 12, did not find expected key, or cannot unmarshal, inspect the specified line and a few lines around it. The parser often points to where it detected the problem, not where it began: the cause may be on the previous line, such as a missing quote, inconsistent list indentation, or a string where a list is required.

Spaces, lists, and special characters

• Use spaces for indentation, not tabs. Align keys at the same level. Two spaces is a common convention, but not the only valid indentation width.
• rules must be a list, with a - before each rule. Use the standard English colon in YAML, not a full-width colon.
• Quote names that contain special characters such as a colon followed by a space or a hash sign, and make sure references match exactly.
• Check for duplicate keys and accidentally merged sections, especially after manually pasting nodes, overriding rules, or merging subscriptions.

The direct-connect configuration below illustrates lists and indentation. It does not include a remote subscription and cannot restore nodes. Its rules refer to proxy groups defined in the same file, so you can compare its structure with the configuration that is failing.

mixed-port: 7890
allow-lan: false
mode: rule

proxy-groups:
  - name: "Default Policy"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,Default Policy

Validate with the active core, not just a YAML parser

A general-purpose YAML parser checks syntax, but cannot confirm that the core accepts the fields, protocols, or policy references. Use the mihomo binary that is actually running on your device: check its version, then test a temporary configuration.

mihomo -v
mihomo -t -f ./subscription.yaml

Here, subscription.yaml must be a configuration file saved locally. If the client's built-in core is not on your command search path, use the actual path to that binary. Testing a configuration with external providers also requires accounting for path and network dependencies. For errors such as proxy not found, check that the referenced node exists, its name matches, and the proxy provider loaded successfully.

Final checklist: get updates working again

1. Preserve the current state: Save a working copy of the old configuration and record the full error, timestamp, client version, and core version.
2. Check your account: Verify the expiration date, data allowance, and token status, then copy the correct subscription URL from your account page.
3. Test the request: Check the HTTP status, redirects, and response body; compare direct and proxied requests separately.
4. Identify the format: Distinguish HTML, JSON, URI lists, full YAML configurations, and proxy-provider files.
5. Check request headers: Verify the User-Agent against the provider's instructions instead of changing it based on guesswork.
6. Validate the configuration: Check YAML indentation, field types, node protocols, and proxy group references.
7. Resume automatic updates: After one successful manual update, set a sensible update interval. Avoid retrying multiple identical subscriptions at once.

If a newly added subscription updates successfully but the original one keeps failing, check the saved URL, request options, override scripts, and local cache in the original entry. Do not immediately clear all configurations; back up first, then troubleshoot that single subscription using the client's documentation. If multiple devices receive the same server error, give the provider the redacted status code, timestamp, and response error details. That is more useful than simply reporting “update failed.”

Confirm an update is successful only when the subscription content has been fetched, the configuration passes validation, and proxy groups load correctly. Test node connectivity separately. If the subscription downloads successfully but nodes cannot connect, investigate the routes, node parameters, and local proxy settings. See the glossary for related terms, and use the Troubleshooting guide to diagnose connection issues.