Clash Subscription Update Failed or Parse Error: URL Format, User-Agent & YAML Troubleshooting

1. Identify the failure: note where the process stops

Keep a copy of the configuration that currently works, then update the subscription manually and note the time and full error. A subscription update passes through DNS resolution, an HTTPS connection, an HTTP response, content parsing, and configuration loading. If an earlier stage fails, changing settings at a later stage usually won’t help.

In the desktop client, open the subscription or configuration list and confirm which entry is being updated. Then check the application or core logs. Labels vary by client, so don’t assume “configuration file updated successfully” means “proxy provider updated successfully.” They may use different URLs and have separate caches.

2. URL format: copy the raw subscription URL, not a login page

Copy it again from your provider’s dashboard

1. Sign in to your provider’s dashboard and select a subscription format explicitly labeled for Clash or compatible with your current core.
2. Use the copy-link button. Don’t piece the URL together from a truncated preview in a messaging app.
3. Check that it starts with https:// and that there are no trailing spaces, line breaks, Chinese full stops, or closing parentheses.
4. Keep the full query string. Don’t delete anything after ? or truncate parameters separated by &.

In webpage source, & is an HTML entity. The actual URL uses & to separate parameters. If the copied URL literally contains &, later parameters may be misread. It’s safer to copy the URL again using the dashboard button than to edit it by hand.

Addresses such as clash:// may be app import commands, not HTTPS subscription URLs you can download directly. A user center, order page, or subscription instructions page in a browser is not a configuration URL either. A page opening in your browser only means the page is accessible; it doesn’t mean it returns YAML.

Check sign-in status and redirects

A download may work in a browser with an existing login cookie, while the client—without that cookie—gets a login page or a denied response. Legitimate subscription APIs typically use a URL token or another API authorization method. Don’t paste browser cookies into scripts from unknown sources; generate a client-compatible URL as described in your provider’s documentation.

If you see a 301, 302, or 307 redirect, check that the final URL still belongs to the expected service. If it redirects to a login page, verification page, or expired domain, resolve the access issue first—not the YAML indentation.

3. HTTP response: save the status code, headers, and raw body

On Linux or macOS, use curl in a local terminal. In Windows PowerShell, call curl.exe explicitly to avoid the same-name alias in older environments. The command below prompts you to enter the URL, so it won’t put the full subscription URL in your command history. Keep in mind that the URL may still be visible on screen as you type it.

# Linux / macOS: create a restricted troubleshooting directory in your home folder
mkdir -m 700 subscription-check
cd subscription-check
umask 077
read -r -s -p 'Paste subscription HTTPS URL: ' SUB_URL
printf '\n'
curl --location --max-redirs 5 \
  --proto '=https' --proto-redir '=https' \
  --connect-timeout 10 --max-time 30 \
  --dump-header response-headers.txt \
  --output response-body.txt \
  --write-out 'HTTP %{http_code}\n' \
  "$SUB_URL"
unset SUB_URL

10 seconds is the connection timeout; 30 seconds is the limit for the full request. These are diagnostic settings for this command, not a performance guarantee. The command doesn’t use --fail, so it saves the response body even when the server returns an error. This helps distinguish an authorization message from configuration data. If the command reports a network error, resolve that first. HTTP 000 does not mean the server sent status code 000.

• 200: Check the response body. A login page, verification page, or JSON error can also return 200.
• 401 / 403: Check the token, subscription status, access restrictions, and response details. A 403 alone doesn’t prove that the User-Agent is the problem.
• 404 / 410: Check whether the path has expired or the domain has changed. Get a new URL from your dashboard.
• 429: If Retry-After is present, wait as instructed. Don’t keep clicking Update.
• 500 / 502 / 503: Note the time and status code, then try again later. Reinstalling the client generally won’t fix a server error.

Open response-body.txt in a local text editor. If it starts with <!DOCTYPE html> or <html, it’s usually a webpage. If it starts with a JSON error object, check its error fields first. Content-Type can be a useful clue, but some APIs label YAML as plain text, so don’t judge validity from the response header alone.

4. User-Agent: compare requests only when there’s a reason

Some subscription APIs choose an output format based on User-Agent; others require an explicit format parameter. If a browser gets proxy share links while a client gets YAML, the API may simply be using different output behavior for each. Check your provider’s supported-client documentation first instead of guessing at browser User-Agent strings.

After entering the subscription URL again in the terminal session above, run this command to compare responses. mihomo is only a test identifier; it may not match the headers sent by your graphical client, and not every API will recognize it.

read -r -s -p 'Paste subscription HTTPS URL: ' SUB_URL
printf '\n'
curl --location --max-redirs 5 \
  --proto '=https' --proto-redir '=https' \
  --connect-timeout 10 --max-time 30 \
  --user-agent 'mihomo' \
  --dump-header response-headers-ua.txt \
  --output response-body-ua.txt \
  --write-out 'HTTP %{http_code}\n' \
  "$SUB_URL"
unset SUB_URL

Compare the top-level fields and status codes in both response bodies. If compatible configuration is returned only with a particular header, check whether your client has a “subscription request User-Agent” setting. Global subscription imports and proxy-providers downloads are separate paths, so changing one may not affect the other. Set headers in the relevant provider configuration only if the documentation for your current core explicitly supports it.

5. Content format: don’t mix up full configs, providers, and share links

A Clash configuration isn’t a catch-all term for any text containing proxy nodes. Responses generally fall into three categories, and each needs to be imported in the right place. A .yaml file extension doesn’t guarantee that the contents match the core’s requirements.

A full configuration can also fetch proxies through proxy-providers, so it doesn’t necessarily include an embedded proxies list. An empty embedded list doesn’t prove the subscription has no proxies. Check whether the provider downloaded successfully and whether the proxy group references the right name with use.

If your provider only returns encoded share links, decoding them still won’t necessarily produce a Clash configuration. Don’t simply rename the decoded text to config.yaml. Use the format provided for your client whenever possible, and avoid giving your subscription credentials to an unfamiliar conversion service.

6. YAML parsing: fix the first error, then check field compatibility

Indentation, quotes, and field types

YAML indentation uses spaces, not tabs. Keep indentation consistent at each level—for example, two spaces per level. If parsing fails “near line 18,” check line 17 as well. A missing quote or colon, or incorrect indentation, is often only detected by the parser on the next line.

• Colons: Use a standard : between a key and its value, usually followed by one space.
• Lists: Start each item with a standard - followed by a space, and indent it correctly under its field.
• Strings: Quote names containing a colon followed by a space to prevent them from being interpreted as mappings.
• Types: Enter numeric fields such as ports as integers, as required by the core. Use true or false for Boolean values, not localized on/off text.
• Duplicate keys: Don’t define top-level rules or proxy-groups more than once. Some parsers reject duplicate keys; others may overwrite the earlier value.

The example below shows only the structure of proxy groups and rules. It contains no remote proxies and is not a complete configuration to use instead of your subscription. Don’t overwrite the file you’re currently using while troubleshooting.

proxy-groups:
  - name: "Manual Select"
    type: select
    proxies:
      - DIRECT

rules:
  - "DOMAIN-SUFFIX,example.com,Manual Select"
  - "MATCH,Manual Select"

The policy name at the end of each rule must match a defined proxy group or built-in policy. If you rename “Manual Select,” update the references in the rules too. Valid YAML syntax only means the text can be parsed; it doesn’t guarantee that proxy protocols, field combinations, or name references are valid.

Test with the core you actually run

You can test a configuration locally with mihomo. First run mihomo -v to note the version, then run the command below. The filename should match the test configuration saved in the current directory.

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

Use the same core version as your graphical client whenever possible. Testing with a separate, newer core only shows whether that version accepts the configuration; it doesn’t prove the client’s bundled core is compatible. Check startup logs for external dependencies such as providers, rule sets, and geodata files.

If the error says a proxy type or field isn’t supported, first check which output format the subscription is targeting. Clash, Clash Meta (mihomo), and different forks don’t support exactly the same configuration features. Don’t delete fields required by a proxy protocol just to suppress an error. Switch to a compatible output or update the core after confirming the client supports it.

7. Empty proxy lists and network failures: verify downloads and loading separately

The update succeeded. Why is the list still empty?

1. Confirm the active configuration: You may have updated configuration A while configuration B is still running. After the update, check the active configuration name and loading logs.
2. Check the provider: The main configuration may download successfully while a proxy provider fails because of DNS, authorization, or network issues.
3. Check filters: filter, exclude-filter, or a search filter in the interface may exclude every proxy. Remove filters in a copy first and see what appears.
4. Check proxy group references: The provider name must match the group’s use value. Declaring a provider alone doesn’t mean its proxies will appear in every group.
5. Distinguish an empty list from a failed latency test: If the proxies appear but latency tests fail, the problem is with the connection or test route—not a subscription that failed to produce proxies.

System proxy, TUN, and local ports

Whether subscription requests use a proxy depends on the client’s update settings and runtime environment. Enabling the system proxy doesn’t guarantee that the background updater will use it, and enabling TUN won’t fix an invalid token or malformed YAML. First confirm whether requests go direct or through an existing proxy, then change one setting at a time.

If the error points to 127.0.0.1:7890, check whether anything is listening on port 7890 and whether the core is running. Port 7890 is a common example, not a fixed value for every client. If the core fails to start and the updater still relies on that local proxy, you can end up in a loop: the configuration won’t load, so the subscription can’t be fetched. If the client supports it, temporarily switch updates to a direct connection and keep the original setting so you can restore it later.

For x509 errors, expired certificates, or certificates that are not yet valid, first sync your system date, time, and time zone. Then check whether you’re on a public network that requires a browser sign-in. Don’t disable certificate verification as a permanent fix. If DNS fails, check system name resolution and the subscription domain. Avoid changing DNS, TUN, rules, and proxy protocols all at once, or it’ll be hard to tell what helped.

8. Verify recovery: confirm twice before restoring automatic updates

1. Update manually once and confirm the response body contains the expected configuration—not a login page or API error.
2. Load the configuration and confirm the logs show no parse errors, the provider finishes downloading, and the expected proxies appear in the group.
3. Select a proxy and confirm it connects successfully. Record proxy availability separately from the subscription update result; one “success” status shouldn’t stand in for every check.
4. Wait a reasonable interval and update again to confirm the result wasn’t just a temporary success from an old cache. Then restore the original automatic update schedule.

If the issue persists, send your provider the client name, actual core version, operating system, time of the error, HTTP status code, and a redacted error line. Don’t send the full token, proxy passwords, or the entire raw configuration. Before deleting local troubleshooting files, keep a summary that contains no credentials. Response headers may contain cookies or redirect URLs with tokens, so treat them as sensitive too.

If you need to choose a different client, see the client comparison. For a quick guide to the differences between rules, proxy groups, and providers, see the concept guide. Keep the recovery sequence the same: validate the URL, check the response, confirm format compatibility, load successfully, and only then test the connection.