Clash Subscription Update Failed? Fix Import and YAML Parsing Errors

First, tell download failures, parsing errors, and unreachable nodes apart

Keep your current working configuration, then check the update log. Subscription updates involve three stages: downloading the response, parsing the configuration, and loading it into the core. Testing node connectivity comes afterward. Treating these as one problem can lead to repeatedly changing rules when the URL is dead, or switching nodes when the real issue is invalid YAML.

ClashX and clients that use the mihomo core may label menus differently and phrase errors differently. Note the client name and version, plus the core name and version—not just the window title. Updating the app shell does not necessarily update the core it runs.

Step 1: Make sure you copied a valid subscription URL

Check the subscription page, token, and plan status

1. Open the Subscription or Import section in your provider account and choose a format explicitly marked for Clash or mihomo. An account login, payment, or node information page is not a subscription URL.
2. Copy the URL again. Check that it starts with https:// and has no trailing spaces, line breaks, or non-ASCII punctuation. Do not remove the query string: its parameters may identify your account or determine the output format.
3. Make sure your plan is active, you have data remaining, and your subscription token has not been reset. If it has, replace the old URL saved in the client.
4. If you received a QR code or one-click import link, check whether the client supports that import method. A link that launches an app is not the same as an HTTPS URL that directly returns a configuration file.

HTTP 401 commonly indicates an authentication failure. A 403 may result from account permissions, access policies, or a security check; a 404 may mean the path has changed. Status codes can narrow down the cause, but a 403 alone does not prove that a plan has expired. Check the response body and your provider account status.

Opening a URL in a browser does not mean the client can update from it

Your browser may have a login cookie or use a different network route from the subscription download. If the URL opens a login form, CAPTCHA, or “Enable JavaScript” page, the client usually cannot parse it as a configuration. Look for a subscription URL the client can read directly; do not copy the webpage source.

Step 2: Check the network path used to download the subscription

First identify whether the error occurs during DNS resolution, the TCP connection, or the TLS handshake. no such host points to DNS; connection refused means the connection was rejected; certificate has expired or a hostname mismatch indicates a certificate issue. For context deadline exceeded, use the surrounding log entries to pinpoint where the timeout occurred.

• DNS resolution failure: First check that your system can resolve the subscription domain, then see whether the client uses its own DNS. If your browser uses secure DNS, its results do not necessarily reflect system DNS.
• Direct connection timeout: If you still have a working node, try updating through it if your client supports that option. Keep the old configuration so you do not lose your update path before the replacement is ready.
• Proxy update timeout: Check that the current proxy node works. If updating depends on a node that has already failed, you can end up in a loop: you need to update before you can connect, but you need to connect before you can update.
• TLS error: Check your system date, time, and time zone, and make sure the certificate for the subscription domain is valid. Do not use certificate verification bypass as a permanent fix.

System proxy, TUN mode, and subscription downloads may use different network paths. Some clients download subscriptions at the application layer; others have the core handle provider updates. If enabling TUN makes the issue disappear, that only shows the network path changed—it does not prove the YAML is valid or mean that everyone should enable TUN.

Reproduce the issue through your local proxy

The following Bash commands are for macOS or Linux. Enter the URL interactively so it is not written directly to shell history; it may still appear in local process arguments while the command runs, so use a trusted device. The response file also contains sensitive information—do not upload it. Test direct access first, then compare with a local mixed port you have confirmed is working.

umask 077
read -r -s -p 'Enter subscription URL: ' SUB_URL
printf '\n'
curl --noproxy '*' --location --connect-timeout 10 --max-time 30 \
  --output subscription-direct.yaml \
  --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.yaml \
  --write-out 'HTTP %{http_code}\n' "$SUB_URL"
unset SUB_URL

7890 is a common mixed port, but replace it with the port your client is actually listening on. If nothing is listening there, the second command will fail with “connection refused”—that does not indicate a problem with the subscription server. These commands do not use --fail, so an HTTP 403 response may still be saved successfully. Check both the HTTP status and the file contents.

Step 3: Identify what the server returned

HTTP 200 only means the request received a successful response; it does not mean the response is a Clash configuration. Open the saved file in a local text editor and inspect the first few lines and top-level fields. Do not execute anything in the file.

Do not confuse a complete configuration with a proxy provider

A complete configuration usually includes proxies, policy groups, and rules. It can also reference external nodes through proxy-providers. A proxy provider file often starts with proxies: and contains nodes only. Importing a node-only file as the main configuration may give you nodes but no expected policy groups; loading a complete configuration as a provider can also cause format errors.

When using providers, check the main configuration load result and the provider download log separately. Valid main configuration syntax does not mean a remote provider updated successfully. If only one policy group is empty, check its use setting, provider status, and filter expression before resetting the entire configuration.

Step 4: Check YAML and referenced names around the reported line

YAML is indentation-sensitive. Use spaces, not tabs, and keep indentation consistent at each level; two spaces per level is common. For mapping values are not allowed or did not find expected key, check the three to five lines above the reported line too. The actual problem may be an unclosed quote on the previous line or a misindented list item.

Test the loading path with a minimal configuration first

This minimal configuration contains no remote nodes. Use it to distinguish “the client cannot load any configuration” from “the subscription is invalid.” It only provides a direct-connection option and does not establish a remote proxy connection. Save it as a separate test file; do not overwrite your subscription.

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

proxies: []

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

rules:
  - MATCH,Select manually

If the test file reports that the port is already in use, exit the other proxy process or choose a free port and update the test command accordingly. A port binding failure is a runtime issue, not a YAML syntax error. If the test configuration loads, go back to the original subscription and look for differences.

Check these four structural issues

• Missing space after a key: Write mixed-port: 7890. Do not use mixed-port:7890 and expect it to parse as the same key-value structure.
• Unquoted names: If a node name contains special sequences such as : or #, wrap the entire name in quotes. Escape any quotes inside the string correctly.
• Reference name mismatch: A node name in a policy group must exactly match its definition, including capitalization, spaces, and symbols. If you rename a node, update its references too.
• Duplicate top-level keys: Do not concatenate configurations into two proxies: or two rules: sections. Parsers may reject duplicate keys or handle them differently; do not rely on one section overriding the other.

Do not identify a file's format by its extension alone. An HTML error page named config.yaml is still not a configuration. Do not bulk-delete fields you do not understand, either: removing authentication, transport, or TLS settings may make the file pass syntax checks but prevent nodes from connecting.

Step 5: Check the active core and protocol compatibility

Clash configurations belong to a family of related but not identical formats. Some protocols and fields supported by the mihomo core may not work with older Clash cores. For example, if a subscription includes type: hysteria2, confirm that the core actually running supports that node type. Do not rename it to another protocol.

1. Check the version in the client's About page or startup log. If the interface does not show core details, look for the core name and version in the logs.
2. Check that the download matches your platform and architecture, and make sure you updated the client that is running—not another copy in a different installation directory.
3. If the log explicitly reports an unknown proxy type or unsupported field, choose a compatible format offered by your provider, or use a client and core that support the feature.
4. Do not remove connection settings such as reality-opts or tls just to silence an error. A configuration being accepted does not mean a node can complete its handshake.

Run the mihomo built-in check command

If the mihomo command-line version is already installed locally, use a terminal to check the saved configuration. The commands below assume the executable is on your PATH and the test file is in the current directory. Check the version first, then run the configuration test.

mihomo -v
mihomo -t -f ./subscription-direct.yaml

The test result applies only to this file and this core. A GUI client may also apply overrides, merge configurations, or run scripts, so even if the terminal test passes, check the runtime configuration the client actually generates. Configurations that use external resources may need network access during testing or later loading. A passing test does not mean every node is online.

Update succeeds but the node list is empty: check filters and active configuration

First make sure the updated configuration is selected. In some clients, updating a subscription card and switching the active configuration are separate actions. If the node list has not changed, check the update time, active configuration indicator, and load log. Avoid repeatedly clicking Update, which may trigger rate limits.

• The response contains no nodes: If the local file contains proxies: [] and there are no other valid node sources, check your account and output settings with your provider.
• The response has nodes, but none appear in the interface: Check for a name search, region filter, regex filter, or exclusion rule. Clear all filters and compare again.
• Only the provider group is empty: Make sure the policy group uses use to reference the correct provider name, then check whether that provider's latest download succeeded.
• The error appears only after import: Temporarily disable custom overrides or merge rules and compare the results; keep a backup. The main subscription and additional configuration may each be valid on their own but conflict when merged.

If the nodes are listed but latency tests time out, troubleshoot the connection instead. An unreachable test destination, a failed node egress, or a local network block can all cause timeouts; none of these proves the subscription failed to parse. Rearranging YAML indentation will not usually help.

Verify the fix and prepare useful troubleshooting details

Change one thing at a time, then update again and check the same log entry. Changing DNS, the core, the subscription URL, and the rules all at once makes it impossible to identify the cause. After fixing the issue, verify each item below to make sure you did more than dismiss an error message.

1. Manually update the subscription once and confirm that the HTTP request succeeds and the update time changes.
2. Confirm that the configuration parses and the core loads it successfully, with no errors about missing nodes, policy groups, or providers.
3. Select a node and open an HTTPS page through the actual proxy route, then test the apps you need. A working browser does not mean every app is using the proxy.
4. Restart the client and confirm that the correct configuration is still active. If you use scheduled updates, check that the next scheduled run succeeds too.
5. Delete any sensitive response files created during troubleshooting and remove temporary configurations you no longer need.

Follow the same troubleshooting order: verify the URL, confirm the response can be retrieved, then check its format, YAML structure, and core compatibility. For more on ports and rules, see the user guide. For account URLs and auto-update issues, continue with the subscription FAQ.