Clash Subscription Parse Failed or Invalid: Causes & Troubleshooting Checklist

Clarify the Problem First: Import Error vs. Empty Node List

Subscription-related issues generally fall into two categories, and the troubleshooting path differs completely for each. The first type is when the client throws an outright error while importing the subscription, with messages like "failed to download subscription," "failed to parse subscription," or "invalid URL." These issues typically occur before or during the client's request to the subscription link. The second type is when the import completes with no error—the client even shows "subscription updated successfully"—but the proxy group or node list ends up empty. This usually means the response was received, but the parser couldn't extract any valid node information from it.

Separating these two cases is essential: the first points you toward the network request and the link itself; the second points you toward the returned data format and field structure. Below is a five-layer checklist ordered from the outside in—work through it step by step without skipping ahead.

Step 1: Confirm the Subscription Link Itself Is Complete and Valid

The root cause of most subscription problems is surprisingly simple—the link itself is faulty. Check each of the following:

• Was the link copied in full? Subscription links are often long and include a lengthy token parameter, so manual copying can easily drop trailing characters or add an extra space or line break. Use the provider's "one-click import" or "copy link" button rather than selecting text manually.
• Does the link protocol match what the client expects? Clash-based clients typically require subscription links to start with http:// or https://. If the provider gives you an invocation link like clash://install-config?url=..., you need to extract the actual url parameter value first and import that separately—don't paste the entire string.
• Has the link expired or been revoked? Some subscription services invalidate old links after a device change or key reset. The old link may still "look normal," but the server is now rejecting requests or returning empty content.
• Can the local network reach the link directly? If the subscription domain itself requires a proxy to access, and the client hasn't connected to any working node yet, you hit a chicken-and-egg problem: no proxy means the subscription can't be fetched, and no subscription means no proxy can be set up. In this case, temporarily disable the system proxy or use direct connection mode to complete the initial subscription fetch.

Step 2: Verify the Format of the Returned Subscription Content

Once you've confirmed the link is reachable, the next step is checking whether the format of the server's response is being correctly recognized by the client. Clash and Clash Meta (mihomo) mainly support two subscription response formats: a standard YAML config with a proxies field, or a Base64-encoded node list (common in generic subscription formats designed for compatibility with older clients). If the returned format doesn't match what the client expects to parse, you'll see the classic "download succeeded but nodes are empty" symptom.

You can inspect the raw subscription response directly from the command line to quickly check whether the format looks correct:

After downloading, open sub-raw.txt and check the following:

1. Is the file valid YAML, does it contain a proxies: field, and is the indentation consistent? (YAML is extremely sensitive to indentation—mixing tabs and spaces will break parsing outright.)
2. If the content looks like a long, seemingly random string, it's likely Base64-encoded. The client needs to automatically detect and decode it; older client versions that don't support this encoding will also show an empty node list.
3. Is the returned content actually an HTML page (a login page, error page, or "traffic exceeded" notice)? This means the request never received real subscription data—it was redirected to a notice page instead, and the client naturally can't parse nodes out of HTML.

Step 3: Check Whether Traffic or Validity Period Has Run Out

Many subscription services, once traffic or time has run out, don't return an outright error—instead they return an empty node list or redirect the response to a notice page. This is one of the most common reasons behind "client shows update successful, but there are no nodes." Two ways to check:

• Log in to the provider's dashboard or client-specific status page and check remaining traffic and expiry date directly—this is the most reliable method.
• Check the Subscription-Userinfo field in the subscription response headers. This field usually includes upload, download, total, and expire values (in bytes and Unix timestamp). Some clients display these values directly on the subscription details page. If upload + download is close to or exceeds total, or if expire is earlier than the current time, that confirms a traffic or validity issue rather than a client configuration problem.

This step matters because it saves you from wasting time reinstalling the client or re-importing configs over and over—if the subscription itself is unpaid or expired, no client setting will bring the nodes back.

Step 4: Check User-Agent and Request Header Restrictions

Some subscription services identify the request source by the User-Agent (UA) header, returning the full node list only to UAs recognized as "legitimate clients," while returning a stripped-down message, an empty list, or even denying access to browser UAs or unrecognized UAs. This is a common way to prevent subscription links from being freely scraped and redistributed. It also explains a common phenomenon: the same subscription link shows abnormal or empty content when opened directly in a browser, but works fine when imported in a client—because the UA sent by the client differs from the browser's.

If you suspect a UA restriction is the cause, try the following:

1. Check whether the client's subscription request UA matches one of the supported UAs listed in the provider's documentation (default UAs vary between clients—Clash Verge, Clash for Windows, and the mihomo core each may use a slightly different default identifier).
2. If the client supports a custom subscription request UA (some clients offer this option on the subscription details page), try switching to the UA string recommended in the provider's documentation.
3. Use a command-line request with a custom UA parameter (like the curl -A example above) to test different UAs and compare the results—this will confirm whether a UA restriction exists.

Step 5: Verify Client Version and Protocol Support Range

Even if the subscription content format is correct, traffic and validity are fine, and the UA isn't being blocked, you may still see an empty or partially incomplete node list. This is often a matter of client version and protocol support range. Common scenarios include:

• The subscription includes a newer proxy protocol (for example, a transport-layer feature only supported by newer core versions), while the current client is running an older core version. The parser silently skips nodes it can't handle instead of throwing an error, so the node list appears to be "missing some entries" without any obvious warning.
• The subscription uses a custom proxy-groups policy group type or a rule-providers remote rule set syntax that an older client's parser can't recognize, causing the entire parsing step to fail.
• The core type selected by the client doesn't match what the subscription requires—some advanced features (fuller rule syntax, certain newer protocols) are only supported under the Clash Meta (mihomo) core. If the client is still running the older, original Clash core, you'll see parsing errors or missing nodes even if the subscription content itself is fine.

When you run into this, prioritize two things: first, upgrade the client and its built-in core to a newer stable version; second, check the provider's documentation to confirm whether the subscription explicitly requires a specific core or client version, then verify that against the client you're actually using.

When to Contact Your Subscription Provider Instead of Continuing to Troubleshoot

The five-layer checklist above covers the vast majority of issues that can be resolved on the client side, but some cases aren't really client problems at all, and further troubleshooting locally won't help. Contact your subscription provider directly when:

1. You've confirmed via the dashboard that both traffic and validity are fine, yet the subscription link keeps returning empty content or an error page over an extended period with no recovery.
2. The same subscription link fails to return any node information across different networks, different clients, and different UAs—essentially ruling out anything on your end.
3. The subscription dashboard itself shows a notice about node maintenance, line adjustments, or service migration—these situations typically require waiting for the provider to restore service, or switching to a new subscription link as instructed.
4. You suspect your account was mistakenly flagged for abnormal behavior and restricted—in that case, explain the situation through the provider's official support channel rather than continuing to retry on the client side.

Rule out everything checkable on the client side first, then contact your provider—describing that you've already verified link integrity, response format, traffic status, UA, and client version will help them pinpoint the issue faster, without needing to go back and forth confirming the basics.