Clash Subscription Link Not Working or Failing to Parse: Common Causes and a Step-by-Step Checklist

First, identify which layer is failing

When a Clash client updates a subscription, it typically resolves the domain, establishes a TCP and TLS connection, sends an HTTP request, receives the response, identifies the subscription format, parses YAML or node URIs, and finally passes the result to a core such as mihomo. The same “update failed” message can refer to entirely different stages. Repeatedly clicking Update usually just repeats the same error.

Before troubleshooting, record the exact error, the time it occurred, and the core version currently used by the client. Do not write down only “it doesn’t work.” Keywords such as timeout, 403 Forbidden, yaml: unmarshal errors, and unexpected end of file can already narrow the problem to networking, access control, or format parsing.

Step 1: Confirm that the subscription link is still valid

Check the copied URL and HTTP status

Paste the link into a plain-text editor first and confirm that it begins with https:// or an http:// address explicitly provided by the service. Messaging apps may truncate links around question marks, equals signs, or hyphens; QR scanning can also insert spaces or line breaks. If the URL ends with parameters such as token= or key=, even one missing character may result in a 401, 403, or empty response.

You can inspect only the response headers from a terminal. On Windows 11, open “Terminal” → “PowerShell”; on macOS, open “Applications” → “Utilities” → “Terminal”. Replace the address in the command below on your own device, and do not share the output publicly:

curl -I -L --connect-timeout 10 --max-time 30 "subscription URL"

-L follows 301 or 302 redirects. The connection timeout is set to 10 seconds, with a 30-second overall limit. Common status codes can be interpreted as follows:

• 200: The server returned content, but that does not prove it is a valid subscription.
• 301, 302, 307, 308: A redirect is present; an outdated client or an unreachable redirect target may cause the request to fail.
• 401, 403: The token has expired, the account is not in good standing, the request does not meet requirements, or the access origin is restricted.
• 404, 410: The endpoint path has changed, or the old subscription URL has been revoked.
• 429: Too many updates were requested in a short period. Stop retrying and wait for the server’s rate-limit window to end.
• 500, 502, 503, 504: The subscription server or an upstream service is temporarily unavailable. Check again after a while.

A browser opening the link does not guarantee that the client can update

The browser and Clash client may use different DNS settings, proxy paths, cookies, User-Agent values, and redirect handling. If the browser displays a downloaded file, that only proves the current browser environment can access it. The client may still fail because of different headers, a proxy loop, or an inability to resolve the target domain.

Also check the account status. After traffic is exhausted, a plan expires, or a subscription URL is reset, some services do not return a clear 401. They may instead return explanatory text or an HTML login page. Once the client receives that content, it often reports “parse failed.” The symptom looks like a YAML error, but the actual cause is that subscription access has changed.

Step 2: Check whether the response is in a Clash-compatible format

Identify full configurations, proxy collections, and generic node lists

Subscriptions commonly use more than one structure. A full Clash configuration is usually YAML and may contain top-level fields such as proxies, proxy-groups, rules, and dns. A proxy collection is typically referenced by proxy-providers, with payload often serving as its core content. Another common format is a Base64-encoded list of node URIs, which reveals entries such as ss://, trojan://, and vmess:// after decoding.

These three types serve different purposes. Importing a collection URL intended only for proxy-providers as a full configuration may produce errors about missing proxy groups and rules. Conversely, submitting a full YAML file to an entry point that accepts only a node list may result in 0 nodes. First confirm whether the provider labels it as a “Clash configuration,” “Mihomo configuration,” “proxy collection,” or “generic subscription.”

A minimal full configuration usually looks roughly like the structure below. A real configuration will also include ports, DNS, and more rules, but the indentation hierarchy must remain consistent:

mixed-port: 7890
mode: rule

proxies:
  - name: example-node
    type: ss
    server: 192.0.2.10
    port: 443
    cipher: aes-128-gcm
    password: example-password

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - example-node
      - DIRECT

rules:
  - MATCH,PROXY

Rule out web pages, error JSON, and truncated files

Use the command below to save the response body, then inspect the first few dozen lines in a text editor. Any local temporary filename is fine:

curl -L --connect-timeout 10 --max-time 30 \
  -o subscription-response.txt \
  "subscription URL"

If the response begins with <!doctype html>, <html>, a login form, or CAPTCHA instructions, it is a web page. If it contains a structure such as {"code":403,"message":"..."}, it is an API error in JSON. If the file suddenly ends inside an unclosed quote, list, or Base64 string, the download may have been interrupted or the server may have generated incomplete content.

• YAML indentation expresses hierarchy, so the hyphen before each list item must be at the correct level.
• Tab characters can make YAML scanning fail; use spaces for configuration indentation.
• Colons, hash signs, braces, and similar characters in node names may need to be enclosed in quotes.
• When duplicate fields appear at the same level, different parsers may handle them differently.
• The Content-Type response header is a useful clue, but it cannot by itself determine whether the content is valid.

Step 3: Compare the User-Agent and request behavior

Some subscription endpoints return different formats based on the User-Agent. For example, they may return an information page to browsers but YAML to Clash or mihomo. Some endpoints also use the User-Agent to select compatible fields. If a browser test returns 200 but the client gets 403 or HTML, compare the request characteristics instead of immediately editing the YAML.

You can use curl to simulate a common mihomo request identifier. Test the default request first, then test with a specified User-Agent. If the results differ noticeably in status code, file size, or body format, the problem is usually in the server’s client-detection logic:

curl -L -A "clash.meta" \
  --connect-timeout 10 \
  --max-time 30 \
  -o subscription-mihomo.yaml \
  "subscription URL"

If specifying clash.meta returns YAML while the default request returns a web page, first use the subscription User-Agent setting provided by the client, or ask the subscription provider which value to use. Menu locations vary between graphical clients; common paths are “Settings” → “Subscription settings” or a configuration’s “Edit” → “Request headers.” Record the original value before changing it, and avoid applying a global header to other configurations by mistake.

Also check rate limits and caching

Clicking “Update” repeatedly can send multiple requests within a few dozen seconds. The server may count requests by token, IP address, or User-Agent, then return 429, 403, or a temporarily empty response. If this happens, stop updating for 10–30 minutes before making one more request. Do not have the desktop client, phone, and router repeatedly fetch the same URL at the same time.

Client caching can also create the illusion that “the link is fixed, but the old error remains.” First note the configuration name and changes in the configuration list, then delete the failed remote configuration and import it again. Do not overwrite a local configuration that is still working. If the client lets you view the configuration directory, compare the cached file’s modification time and size: an unchanged timestamp indicates a download-stage failure; a changed timestamp followed by an inability to enable the configuration points more toward parsing or core loading.

Step 4: Check mihomo core and configuration-field compatibility

Even after a subscription downloads successfully, the core still has to parse it. Clash Premium, older Clash versions, Clash Meta, and current mihomo do not support exactly the same protocol fields and features. When a subscription service upgrades its template, it may add proxy types, transport parameters, DNS fields, or rule-provider options that an older core does not recognize. The same URL may work in a newer client but fail in a client that has not been updated for a long time.

Use the log to locate the specific field

Open the client’s “Settings” → “Logs”, temporarily set the level to info or debug, and perform the subscription update or configuration switch once more. Restore the original log level afterward. Look specifically for the following messages:

• unsupported proxy type: The current core does not support a proxy type used in the subscription.
• field ... not found or a deserialization error: The field name, value type, or version compatibility is incorrect.
• proxy ... not found: A proxy group refers to a missing node or another missing proxy group.
• rule provider ... error: The main configuration loaded, but an external rule collection failed to download or parse.
• bind: address already in use: The configuration may have parsed successfully; the failure is that a port such as 7890 is already occupied.

Handle core compatibility issues through the client’s built-in core update option first. A common path is “Settings” → “Core” → “Check for updates.” After updating, fully exit and restart the client, then confirm that the actual core version shown in the log has changed. Updating only the graphical interface while continuing to use an old core will not remove the error.

Distinguish subscription parsing from rule-provider failures

A full configuration may continue to reference remote proxy-providers and rule-providers. A successful main subscription download does not mean these child resources are reachable. If the node list exists but switching configurations reports a rule-collection failure, check the specific URL, HTTP status, and cache path in the log instead of regenerating the main subscription.

For example, the main configuration may be reachable directly while the rule-collection URL requires a proxy. If the proxy has not been established when the client starts, this can create a startup dependency. Temporarily disable the relevant remote rules to confirm that the main configuration runs, then adjust the rule collection’s download path or update policy. After editing YAML, check the indentation before loading it with the client’s configuration checker.

Step 5: Check the local network, DNS, and proxy loops

Test with the system proxy disabled first

A subscription update is generally initiated by the client itself, but different clients may connect directly, use the system proxy, or access the URL through the current proxy policy. If the current node is already down and the subscription domain is routed through that node, a loop can occur: the subscription must be updated to restore the nodes, but updating the subscription depends on the failed node.

1. Record the current configuration and proxy-group selection.
2. Turn off “Settings” → “System proxy”.
3. If TUN mode is enabled, also turn off “Settings” → “TUN mode”.
4. Exit other proxy programs using ports 7890, 7891, or 7892.
5. Test the subscription URL again over a direct connection.
6. After the update completes, re-enable the system proxy and TUN in sequence.

If the update immediately works after disabling the system proxy and TUN, the root cause is usually a routing rule, current policy, or proxy loop—not the subscription format. Check whether the subscription domain is being sent through the wrong proxy policy. Add an explicit direct rule for the domain and make sure it appears before broad proxy rules.

rules:
  - DOMAIN,subscription.example.com,DIRECT
  - MATCH,PROXY

The domain above is only an example of the structure; use the actual hostname of the subscription service in a real configuration. If the subscription goes through multiple redirects, check the final redirect domain as well. Allowing only the entry domain may still leave the second hop blocked.

Check DNS, system time, and TLS

Run nslookup subscription domain in a terminal and confirm that it returns an address. If the browser uses secure DNS while system resolution fails, the client may not be able to reuse the browser’s DNS result. Temporarily switch to another network, such as a phone hotspot, and test again. If the problem disappears on the other network, the likely cause is the current DNS, router filtering, or network egress.

TLS certificate validation also depends on the system clock being correct. A device date that is off by a day, an incorrect time zone, or a clock that has not synchronized for a long time can trigger errors such as certificate has expired and not yet valid. On Windows 11, go to “Settings” → “Time & language” → “Date & time” → “Sync now”; on macOS, go to “System Settings” → “General” → “Date & Time” and enable automatic setting.

A firewall or security application may restrict only the client process while leaving the browser unaffected. Check the system firewall’s allowed-app list and confirm that both the current Clash graphical client and the mihomo core process can establish outbound connections. Do not disable the firewall permanently for testing; instead, review blocked-connection records and create a narrowly scoped outbound rule for the relevant programs.

Complete one full checklist in a fixed order

To avoid changing several variables at once, follow the order below. Test only once after each step and record the status code, file size, or log changes. This makes it clear which adjustment produced the result.

1. Preserve the evidence: Record the exact error, time, client version, core version, and current network.
2. Check the URL: Confirm that the link is not truncated, the account is valid, and the token has not been reset.
3. Check HTTP: Test the status code and redirects with a 10-second connection timeout and a 30-second overall limit.
4. Inspect the body: Rule out an HTML login page, JSON error, empty file, or truncated download.
5. Confirm the type: Distinguish a full YAML configuration, proxy collection, and generic node list.
6. Compare request headers: Test the response difference between the default User-Agent and clash.meta.
7. Check compatibility: Update the client core and use the log to locate unsupported fields or protocols.
8. Isolate network variables: Temporarily disable the system proxy and TUN, then test with a direct connection or phone hotspot.
9. Import again: Keep a backup of the old configuration, delete the failed cache, and add the remote configuration again.
10. Verify the result: Confirm that the node count, proxy groups, rule collections, and update time all match expectations.

Verify that the configuration actually works after recovery

“Update successful” on the subscription page is only the first level of verification. Also confirm that the configuration timestamp has refreshed, the node list is not empty, proxy-group references work, and a latency test completes. A latency result with a specific value, such as 85 ms or 230 ms, shows that the test URL can establish a connection through the corresponding node; repeated timeouts mean you should continue checking the node or local network.

Then open the connections panel and visit a regular HTTPS page. Check whether a new connection appears, which rule it matched, and which proxy group and node it used. In rule mode, the subscription site can connect directly while other destinations are routed according to the rules; global mode sends most traffic through the current global policy. During verification, confirm that the active mode matches your expectations.

If the system proxy uses the default mixed port 7890, also check that the operating system proxy address is 127.0.0.1:7890 and that the log contains no port-occupation errors. TUN users should check the TUN status, default route, and DNS recovery rather than relying only on a browser page loaded from cache.

Once stable, set a reasonable automatic update interval for the remote configuration, such as 6, 12, or 24 hours. Polling every few minutes is usually unnecessary and may trigger server-side rate limits. After upgrading the client, switching cores, or changing the subscription template, perform one manual update and configuration check.