Clash Subscription Parse Errors: URL, YAML Indentation & Headers Checklist

First, distinguish download failures, parse errors, and empty node lists

Importing a Clash subscription involves several steps: the client requests the subscription URL, receives the response body, converts or parses it into a configuration, and passes it to the core for loading. A message such as “Update failed” may combine several of these steps. Open the client’s log and note when the failure occurred and the exact error before deciding whether to check the link or the configuration.

Menu names vary between Windows clients. The subscription entry may be called “Subscription” or “Profiles,” while logs are usually under “Logs.” Find the failing subscription, update it once, then check the logs from around the same time. This helps prevent a node latency-test failure from being mistaken for an import failure.

Step 1: Check the subscription URL and HTTP response

Copy the subscription URL, not the account page URL

1. Return to the provider’s subscription page and choose an entry explicitly labeled for Clash or Clash Meta/mihomo.
2. Copy the entire URL again. Check that it starts with https:// or a provider-supported http://, and has no trailing newline, punctuation, or extra spaces.
3. Check that all query parameters are present. If a URL containing & is truncated, only the first parameter may remain. When copying from page source, also check that the literal text & was not included by mistake.
4. If you recently reset the subscription token, replace the URL in the client. The old link will not become valid again just by clicking Update.

A URL without a .yaml suffix is not necessarily in the wrong format. Conversely, a URL ending in .yaml may still return a login page or an error. Check the server’s status code and response body instead.

Save the actual response on Windows

Run the following command in Windows PowerShell. It uses the system’s curl.exe to avoid confusion with command aliases in some PowerShell versions. First, switch to a temporary directory that only you can access. The URL is read through a prompt, so you do not have to place a token-bearing link directly in command history.

$url = Read-Host 'Paste subscription URL'
curl.exe --location --max-time 30 --dump-header response-headers.txt --output subscription-response.txt -- "$url"
Get-Content .\response-headers.txt
Get-Content .\subscription-response.txt -TotalCount 12
Remove-Variable url

--location follows redirects, while --max-time 30 limits the total request time to 30 seconds. If there are multiple sets of response headers, check the status in the last set. Saving a file successfully only means a response was received; it does not mean the response is a valid subscription. Response headers may also contain sensitive redirect URLs, so remove these files after troubleshooting.

• 200: Check the body. A login page or application error can also return 200.
• 301, 302: Confirm the final destination is subscription content, not a login or verification page.
• 401, 403: Check the token and access policy; server-side protection may also have rejected the request.
• 404, 410: Check whether the subscription entry has changed and ask the provider to confirm the link status.
• 429: Stop retrying and wait as directed by the server to avoid triggering further rate limits.

Being able to open a URL in a browser does not mean the client can download it. The browser may have a login cookie, use a different proxy route, or have already passed a web verification step. Do not treat an account page that looks “normal” in a browser as proof that the subscription is valid.

Step 2: Identify whether the response is YAML, a node list, or a web page

The first few lines of the response file can usually narrow down the problem. Content-Type is a useful clue, but some services label YAML as plain text, so do not rely on the response header alone.

A “proxy provider file” is not the same as a “full configuration.” The former often contains only a proxies list, which must be referenced by proxy-providers in the main configuration. It may not include policy groups or rules, so importing it as a full configuration will not automatically create all routing options.

If you need to convert a format, prefer a clearly documented, built-in client feature or a format option provided by the service. Do not submit a token-bearing subscription URL to an unknown online converter; the service can read both the URL and the node credentials it returns.

Step 3: Check YAML indentation, quotes, and field types

Check the reported line, then inspect the level above it

The line number in an error message is usually where the parser detected a problem, not necessarily where it began. For example, a missing quote or incorrect indentation on the previous line may not trigger an error until the next line. Open the file in a local text editor, enable line numbers and whitespace markers, and inspect the reported line plus the five lines before and after it.

• Use spaces for indentation, not tabs. Two spaces per level are easy to read, but the important thing is to align items at the same level consistently.
• Use a plain : after a key. Mapping values usually need a space after the colon, as in mode: rule.
• Start list items with a plain hyphen followed by a space, as in - DIRECT. An em dash is not a substitute.
• Quote strings that contain a colon followed by a space, special symbols, or ambiguous text. For example: name: "Hong Kong: 01".
• Do not repeat keys such as dns or rules at the same mapping level. Parsers may handle duplicate keys differently.

The direct-connection test configuration below illustrates the hierarchy. It contains no remote nodes, so it cannot verify subscription recovery or proxy connectivity. Use it only in a local test copy; do not overwrite a working subscription with it.

mixed-port: 7890
allow-lan: false
mode: rule
log-level: info

proxy-groups:
  - name: "Local test"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,Local test

proxy-groups is a list, and each policy group in it is a mapping. The group’s proxies entry is another list. rules and proxy-groups both belong at the top level; do not indent rules under a policy group. The 7890 value is only an example listening port. Use the port shown by your client.

Valid YAML syntax does not guarantee valid field types

A list written as a string may still be valid YAML, but it does not meet the core’s requirements. For example, proxies: "DIRECT" is a different data type from the list shown above. When you see cannot unmarshal, check whether the field expects a string, number, Boolean, list, or mapping—not just whether the spacing is correct.

If the original subscription loads but an error appears only after adding an override, first disable the subscription’s overrides, merges, or scripts, then restore them one at a time. The original subscription saved by the client may differ from the final configuration passed to the core, so inspect the effective configuration. For more details on fields, see the rule syntax guide and the DNS configuration reference.

Step 4: Check the User-Agent and mihomo core support

The same URL can return different formats

Some subscription APIs identify the client from the request’s User-Agent header. A browser, command-line tool, and client may receive different content. The command-line result above is only one sample and may not exactly match the response received by the client.

If the client has a “Subscription request headers” or “User-Agent” setting, record its current value and check the provider’s documentation. The command below sets the request header to mihomo to compare responses. It is not a universal fix for subscription services, and it does not turn an older client into a mihomo core.

$url = Read-Host 'Paste subscription URL'
curl.exe --location --max-time 30 --user-agent "mihomo" --output response-mihomo.txt -- "$url"
Get-Content .\response-mihomo.txt -TotalCount 12
Remove-Variable url

If the default request returns a list of node links but the request with a specified header returns YAML, the server is likely distributing formats based on the request. Use an entry point or header explicitly supported by the provider rather than trying many identity strings. If both requests return a verification page, changing YAML or the User-Agent usually will not resolve the server’s access restriction.

Record the client and core versions separately

Clash, Clash Premium, and Clash Meta (now called mihomo) have different capabilities. If a configuration includes node types such as type: hysteria2 or type: vless, confirm that the current core supports the protocol and its specific parameters. Updating the client interface does not necessarily update or switch the core that is running.

1. Record the client version from the “About” page or version information.
2. Record the core name and full version number from the core information or startup log.
3. Check the configuration documentation for that version, especially the protocol type and transport parameters.
4. Choose a subscription format compatible with the core, or update the core through the client’s official update option.

Do not work around an error by deleting type or renaming a protocol. The protocol type determines how a connection is made; changing it arbitrarily may pass structural checks but will usually prevent a connection.

Step 5: If import succeeds but the node list is empty, check the reference chain

When the node list is empty, first check whether the original subscription contains any nodes, then check whether they remain in the client’s effective configuration. Also distinguish between nodes that were never downloaded and nodes that exist but are not referenced by the active policy group.

• Direct nodes: Check whether proxies is an empty list. If the response itself contains proxies: [], check the account status and subscription filters first.
• Remote proxy providers: Check the download logs for proxy-providers. A successful main configuration download does not mean that every provider updated successfully.
• Policy group references: When using use to reference a provider, its name must match a key under proxy-providers. When using proxies to reference nodes, the node names must also match.
• Filters: Temporarily disable any name filters you added. A regular expression, capitalization, or change in region naming can reduce the results to zero nodes.
• Merge order: Check whether an override replaced the original subscription’s nodes or policy groups with an empty list. Merge behavior varies between clients; do not assume lists are always appended automatically.

For example, if a policy group uses use: [Provider nodes] but the provider is named Subscription nodes, they will not match automatically. Fix the reference, update the relevant provider, and check the logs. Do not repeatedly update only the main subscription.

Retest steps and what to include in a problem report

Change one condition at a time so you can tell which adjustment helped. First confirm the subscription response is correct, then check YAML and core compatibility, and finally restore overrides and traffic interception features. Retesting in the order below is usually more effective than changing DNS, ports, and TUN settings all at once.

1. Import the original URL into a test subscription, disable personal overrides, and update it once.
2. Confirm the logs show no download or parse errors, then check the node count and policy group contents.
3. Select a real node and run a latency test. A failed test is a connection issue to investigate afterward, not a subscription parse error.
4. Restore the system proxy as needed and test browser access. If you need TUN, enable it separately and test the target application.
5. Restore custom rules, overrides, and filters one at a time. After each change, check whether the core loads successfully.

When reporting an issue to the service provider or client project, include the Windows version, client version, core name and version, time of failure, HTTP status, exact error type, and whether the original subscription loads on its own. For YAML issues, provide a redacted excerpt that preserves the indentation and include the original line numbers.

Do not share subscription tokens, server passwords, UUIDs, complete node URLs, or entire response files. If a link has been exposed, reset its token with the provider first, then replace the subscription URL in the client. For checks after a successful import, see the subscription import guide and connection verification guide.