Clash Subscription Update Failed or Parse Error? Common Causes and Troubleshooting Checklist

1. Capture the error and identify where the update failed

Updating a subscription involves several steps. The client first requests the subscription URL, then parses the response, checks whether the config is compatible with the core, and finally loads proxies, proxy groups, and external resources. An “update failed” message can refer to any of these stages. Identifying where it failed is more useful than repeatedly reinstalling the client.

1. Open the client’s Subscription or Profiles page, find the config that failed, and note its name and last updated time.
2. Open the log, clear the old entries or note the current time, then return to the config and click Update once. Depending on the client, the button may say Refresh or Update subscription.
3. Return to the log and find the first error that appeared after the update. Record the error type, HTTP status code, line number, and field name—not just the final “failed” line.

2. Check the URL: make sure you copied the subscription link

1. Copy a fresh Clash-format link from your provider’s dashboard

Sign in to your subscription provider’s dashboard and choose Subscription → Copy subscription URL. Select an output format explicitly labeled Clash or Mihomo. The account homepage, plan purchase page, and QR code image URL are not config URLs. A QR code may contain a deep link that opens a client, so use the original HTTPS subscription URL from the dashboard whenever possible.

• Check that the URL starts with a complete https:// and has no trailing spaces, line breaks, or punctuation added by a chat app.
• Keep the query parameters after ?. Tokens are often included in the parameters or path; removing them may result in a 401 or 403.
• If the URL was reset, the old link may stop working immediately. Edit the subscription URL in the existing config and update it, taking care not to select an older config with the same name.
• Check your account’s expiration date and data usage. Providers may indicate account status through an HTTP status code or a message in the response; check your account dashboard for details.

2. Check the response body along with the status code

A 401 usually means valid credentials are required. A 403 may indicate an access policy, token permissions, or a security block. A 404 may mean the path changed, or the server may use it to hide an invalid resource. If you get a 429, stop refreshing and wait as instructed by the server. If the response includes Retry-After, follow that value. A 5xx error usually requires the provider to check their server, but also consider whether an intermediary gateway returned the error page.

HTTP 200 only means the request received a successful response; it doesn’t guarantee the body is a Clash config. If the response starts with <!DOCTYPE html> or contains a login page, CAPTCHA, or plan details, the parser received a web page. Fixing YAML indentation won’t help—you’ll need to address the URL or the content returned by the server first.

3. Check the network: test direct, proxy, and DNS separately

Being able to open your account dashboard in a browser doesn’t mean the client can fetch the subscription. The dashboard and subscription may use different domains, and the browser, client UI, and core may each use a different network path. Keep other settings unchanged and test one variable at a time.

1. Check your system clock. Turn on automatic time synchronization under your system’s Date & Time settings. A significantly incorrect date can cause TLS certificate validity checks to fail.
2. Check the update method. Look for options such as Update through proxy or Update method in the config menu or subscription settings. If available, test both a direct connection and an update through your currently working proxy, and note the results.
3. Try another network. If permitted, temporarily connect your computer to a mobile hotspot and update the same subscription. If it fails on only one network, check that network’s DNS, authentication, or access restrictions first.
4. Check the local proxy port. Open the client’s Settings and confirm that its HTTP or mixed port is actually listening. Don’t assume the default value from an online guide is correct.

Use a local command to distinguish response errors from connection failures

If you’re comfortable with the command line, compare two request paths on your computer. The example below prompts for the subscription URL so it won’t be written directly to your command history. Port 7890 is only an example; replace it with the HTTP or mixed port shown in your client. These commands work in common Bash and Zsh environments, and save the response to a local file in the current directory.

printf 'Enter subscription URL: '
IFS= read -r SUB_URL
curl --noproxy '*' --location --connect-timeout 10 --max-time 30 \
  --output subscription-direct.txt --write-out 'HTTP %{http_code}\n' "$SUB_URL"
curl --noproxy '' --proxy http://127.0.0.1:7890 --location \
  --connect-timeout 10 --max-time 30 \
  --output subscription-proxy.txt --write-out 'HTTP %{http_code}\n' "$SUB_URL"
unset SUB_URL

These commands use a 10-second connection timeout and a 30-second total time limit to make the results comparable. These are diagnostic settings, not recommended defaults for all clients. The file may contain proxy passwords and tokens, so delete it securely after inspection and don’t sync it to a public repository. A command-line test cannot fully reproduce the client’s User-Agent, request headers, or core routing. If the results differ, treat that as a clue—not proof that either side is at fault.

If the log says no such host, first check whether your system can resolve the subscription domain. If the subscription request hasn’t reached the core, changing dns: in the YAML may not take effect. TUN changes how some traffic is routed, but it can’t fix an expired token or invalid format. While troubleshooting, don’t change TUN, DNS, and rule mode at the same time.

4. Check the format: troubleshoot YAML errors separately from core incompatibility

Check whether you received a full config or just a proxy list

A full Clash config commonly includes top-level fields such as proxies, proxy-groups, and rules. It may also reference external proxies through proxy-providers, so the lack of inline proxies doesn’t mean the response is empty. Conversely, a list of protocol share links, a generic Base64 subscription, or a proxy list intended only for a provider is not necessarily a full config you can activate directly.

Check the client’s import requirements, then confirm the output format provided by your subscription service. Choose a matching format unless the client explicitly supports automatic conversion. If conversion is needed, use a method supported by the provider or a trusted local process. Avoid giving your access token to an unfamiliar online service.

Check indentation and data types around the reported line

The line number in the log is a starting point, not proof that the error is on that exact line. For example, an error on line 12 may be caused by a missing quote on line 11. YAML indentation must use spaces, not tabs; colons must be followed by the right separators, and list items need a hyphen. The snippets below show nesting only and cannot be imported as a complete subscription on their own:

proxy-groups:
  - name: "Manual selection"
    type: select
    proxies:
      - "Proxy A"
rules:
  - "MATCH,Manual selection"

• mapping values are not allowed: Check colons and indentation, and make sure the previous line isn’t missing a quote.
• cannot unmarshal: Check whether the field expects a string, list, or mapping; changing spaces alone won’t fix it.
• If a proxy group references a missing item, compare the proxy and group names, including capitalization, spaces, and symbols.
• Editing only the cached file downloaded from a remote subscription may not last: the next update can overwrite it. Make changes in the source config or a client-supported override layer instead.

Check which core is actually running

Open Settings → About or the client’s core information page, and note both the client version and the core version; they are not the same. Clash Meta is now commonly called mihomo. Supported protocols and fields vary across forks and versions. If you see unsupported proxy type, check compatibility for the specific protocol named in the error instead of deleting the field to force the config to load.

Back up your config before changing clients or cores, then get a compatible version from a trusted release channel. If your device can’t run the required core, ask your provider whether they offer a compatible output format. Updating the client UI alone may not switch the core that’s running; after updating, check the core information page to confirm.

5. Update succeeds but the proxy list is empty: check the active config and providers

“Subscription updated” may only mean the main config was downloaded. It doesn’t confirm that every resource referenced by the config was fetched successfully. With proxy-providers, in particular, the proxy file is fetched separately and may have its own URL, cache, and update schedule.

1. Confirm which config is active. Return to the Profiles or Subscription page and check that the selected indicator is on the config you just updated. Updating config A doesn’t automatically switch you from config B to A.
2. View all proxy groups. Open the Proxies page and expand the group that actually references the proxies. Some home screens show only the current policy, not the full proxy list.
3. Check provider status. If the client has a Proxy Providers page, check the proxy count, last updated time, and errors. If there’s no dedicated page, look for the provider name and download errors in the log.
4. Check filters. A regular expression filter may exclude every proxy. Test by removing the filter in a backup copy or local override; don’t damage your only working config.
5. Check proxy group references. The provider name must match the name used in the proxy group’s use field. If the provider has proxies but no group references it, the expected proxies may not appear in the UI.

If the log reports a failed rule-providers update, check the rule file’s URL and format separately. A rule resource error doesn’t mean the proxy subscription is empty, but it may affect config loading or routing. Use the specific log message to guide your next step.

6. Verify the fix and prepare details if you need help

After troubleshooting, verify the three stages: update, load, and connect. Manually update once and check the log for new subscription request errors. Then activate the target config and confirm the proxy or provider count is as expected. Finally, select a proxy and test a service you normally use; check the connection page for the actual exit IP and rule match.

• Verify the update: Note the time of the update and confirm that the config’s last updated time changes. If you use providers, check their update times too.
• Verify loading: Confirm there are no YAML, protocol type, or proxy group reference errors, and that the target config is actually active.
• Verify the connection: Check that the system proxy is enabled, or that TUN is enabled when needed. Traffic that isn’t being routed through the client can otherwise look like a subscription problem.
• Verify persistence: Restore a reasonable automatic update schedule and check that the next update preserves any required local overrides.

If it still fails, include these details

When contacting your subscription provider or client maintainer, include your operating system, client version, core name and version, failure time and time zone, the full error with sensitive details redacted, and a comparison of direct versus proxy updates. Saying whether the response was an HTTP error, a web page, or a YAML parse error can save several rounds of questions.

If you need to share part of your config, include only the fields needed to reproduce the issue and replace server addresses, passwords, and access tokens. If you’ve exposed the full subscription URL, reset it in your account dashboard and update the saved URL in your client. For help organizing your config, see the subscription chapter in the full handbook. Keep remote subscriptions, proxy providers, and local overrides in their respective layers.