Clash Subscription Update Failed: Fix Config and YAML Errors

1. Tell download, parse, and activation failures apart

A subscription update involves at least three steps: the client requests the subscription URL, reads and parses the response, then passes the config to the core to load. An “update failed” error can occur at any step. If nodes cannot connect, the config may already have loaded successfully, making that a separate issue. Identify the failing stage before changing anything—this helps avoid altering DNS, ports, and rules all at once.

1. Keep a working config: Check which config is selected on the “Profiles” page, and back up your local config and override files first. Don’t delete your only working subscription just to test.
2. Run one manual update: Note when you click Update, then open “Logs” and find the first error around that time. The final “update failed” message is usually just the outcome.
3. Note your environment: Record the client name, client version, and core version from “Settings” → “About” or the client’s version information page. Menus vary by client, and the desktop app version is not the same as the mihomo core version.
4. Check how widespread the issue is: Is one subscription failing, are all subscriptions failing, or is only a specific proxy-providers update failing? Each points to a different troubleshooting path.

2. Check the subscription URL and HTTP response

Copy a fresh subscription URL from your provider’s dashboard

Sign in to your provider’s dashboard, select the Clash or Mihomo format in the subscription section, and copy the full URL again. Don’t copy the account page URL from your browser’s address bar or use the QR code image URL as the subscription URL. The query parameters after ? often contain authorization data; leaving any out can return a login page or an access error.

If you recently reset the subscription URL or token in the dashboard, the old URL may have stopped working immediately. Update the URL in the existing profile instead of continuing to use the old one. An expired account may also return an informational page; check the dashboard and HTTP response rather than assuming every 403 means the account has expired.

• 401: Usually an authentication issue. Check the token and the server’s requirements.
• 403: May indicate insufficient permissions, source restrictions, or a security rule. Check the response body for details.
• 404: Check the path and whether the URL has changed. Some services also use this status to hide invalid URLs.
• 429: Too many requests. Stop retrying and wait as directed by the server or the Retry-After header.
• 5xx: Likely a server-side or gateway issue. Keep your current config and try again later.

HTTP 200 doesn’t guarantee a usable config

A successful status code only means the server returned a response. If the body starts with <!DOCTYPE html> or <html>, it’s usually a web page, login page, or verification page. If it contains only share links such as ss:// or vmess://, or a block of Base64 text, it may not be the complete YAML config required by your client’s import method.

If a browser can download the subscription but the client can’t, the requests may differ. The browser might include a login cookie, use a different proxy route, or receive a different format based on its User-Agent. Use the client-specific option in your provider’s dashboard first; don’t start by arbitrarily spoofing request headers.

3. Check DNS, proxy routing, and TLS errors

Subscription requests may come from the desktop client or the core. DNS settings in the config don’t necessarily control the desktop client’s own update requests, and enabling the system proxy doesn’t guarantee the updater will use it. Check the subscription profile’s menu for update options. If it offers “Direct” and “Via proxy,” test each once for comparison.

Test a working route first to avoid relying on a broken config

If updates require a proxy but the current config is unusable, you can get stuck in a dependency loop. Switch to a saved working config before trying a proxied update, or test a direct update on a network that allows direct connections to the subscription hostname. TUN mode changes how traffic is routed. Note its current state, then temporarily turn it off and test one variable at a time using a confirmed system proxy or an explicitly configured proxy.

These PowerShell commands prompt you to enter the URL and test both a direct connection and a local HTTP proxy. The example proxy address is 127.0.0.1:7890; use it only if the client settings show 7890 as the HTTP or mixed port. A SOCKS-only port cannot be used as an HTTP proxy.

$subscription = Read-Host "Paste subscription URL for local checks only"
curl.exe --noproxy "*" --location --connect-timeout 10 --max-time 30 --output NUL --write-out "HTTP %{http_code}\n" "$subscription"
curl.exe --proxy http://127.0.0.1:7890 --noproxy "" --location --connect-timeout 10 --max-time 30 --output NUL --write-out "HTTP %{http_code}\n" "$subscription"
Remove-Variable subscription

Here, 10 seconds is the connection timeout and 30 seconds is the total request time limit—not a speed test. The command displays only the final HTTP status, not the response body. 000 is not an HTTP status code; check curl’s error message for more information. Interactive input avoids putting the actual URL directly in command history, but local process inspection may still expose runtime arguments, so don’t run this on a shared device.

• Direct fails, proxy works: Check whether subscription updates are using the expected proxy route.
• Direct works, proxy fails: Check the local listening port, current proxy route, and update proxy settings.
• Both methods fail to resolve the hostname: Check system DNS and confirm the subscription hostname is still valid. Don’t just add DNS servers to the config at random.
• x509 or certificate validity errors: Check the system date, time zone, certificate chain, and HTTPS inspection software. On a corporate network, ask an administrator to verify the trust chain.

4. Fix YAML syntax and field types using the line number

If the log reports a parse-stage error such as yaml: line 12, some content was received, but it may not be a config. First make sure it isn’t an HTML error page. Then use a local text editor to inspect the reported line and the 3–5 lines around it. The reported line may be where the parser could no longer continue; the missing colon or quote could be on the previous line.

Check these four common formatting issues first

1. Inconsistent indentation: YAML uses spaces, not tabs. Keep indentation consistent at each level. List markers (-) and their child fields must line up correctly.
2. Full-width punctuation: Replace full-width colons after field names with a standard :. Check that your input method hasn’t changed commas or quotation marks either.
3. Wrong value type: allow-lan must be a boolean, and mixed-port must be a port number. Don’t substitute objects, lists, and strings for one another.
4. Unquoted special characters: Watch for strings containing a colon followed by a space or a space followed by a hash. Enclose addresses and names in matching quotes when needed.

This minimal config illustrates the structure. It only provides a local mixed proxy port and routes traffic to DIRECT. It has no remote proxy nodes and is not a substitute for a subscription if you expect to keep the same routing. Traffic will go direct if you enable it for testing.

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

proxies: []

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

rules:
  - "MATCH,Manual selection"

If a local file loads but the subscription file doesn’t, investigate the subscription content, merge scripts, or override settings. Manual changes to a remote subscription are usually overwritten at the next update. Test fixes on a copy first, then use the client’s persistent override feature if available, or ask your subscription provider to fix the source file.

5. Check core compatibility and config references

Valid YAML only means the syntax can be read; it doesn’t guarantee the core can run it. Clash, Clash Meta (now called mihomo), and different core versions support different protocols and fields. An older core may report unsupported proxy type for an unsupported proxy type. Some unknown fields may also be ignored, so “no parse errors” doesn’t mean the related feature is working.

Trace references based on the specific error

• Unsupported proxy type: Check the subscription’s export format against the core you’re actually running. Use a compatible config or update the core using a method supported by your client.
• Missing policy or proxy: Check the nodes and group names referenced in proxy-groups, along with the policy names at the end of rules. Names must match exactly; check capitalization and trailing spaces.
• Missing rule set: A RULE-SET name used in a rule must have a matching definition in rule-providers. Don’t copy the reference without its definition.
• Port already in use at startup: address already in use is a loading or listening issue. Check whether two clients are running at once; changing the subscription token won’t help.

Also distinguish full configs from provider files. A full config may include sections such as proxies, proxy-groups, and rules. A proxy provider file typically supplies a proxies list referenced by proxy-providers in the main config. A rule provider supplies rule content in the declared format; YAML rule providers often use payload. These files serve different purposes, so don’t import them through the same entry just because they share the .yaml extension.

If the error points to a specific provider, check its URL, format, and update log first. A successful main subscription update doesn’t mean every provider refreshed successfully. Client overrides, merges, and scripts can also change the final config. Temporarily disable the relevant processing on a copy and compare the original config with the final runtime config to find where the error was introduced.

6. After an update succeeds, confirm the new config is active

“Download complete” and “currently active” are not the same thing. Go back to “Profiles” and check the selected profile, update time, and node count. Then open “Proxies” and see whether the policy groups have changed. If the download succeeds but core validation fails, the client may keep running the old config. Check the load log instead of relying on the update notice.

1. Make sure you updated the subscription in use, not another profile with the same name.
2. Check the load log after the update for rollbacks, port conflicts, or missing references.
3. On the “Proxies” page, select a working policy group and test a single node if needed. Don’t mistake testing every node for testing a subscription download.
4. If the browser still can’t connect, check the system proxy, TUN, and rule matching. That’s a traffic routing or outbound connectivity issue, not a subscription parsing problem.

Don’t verify the result by repeatedly restarting the client or setting an extremely short auto-update interval. Repeated requests in a short period can trigger a 429 and obscure the original issue. One complete “request succeeded → validation succeeded → load succeeded” sequence is more useful than clicking Update over and over.

7. Minimum details to include when reporting an issue

If local troubleshooting doesn’t resolve the problem, contact your subscription provider or the client maintainer. “Import failed” alone usually isn’t enough to reproduce the issue. The details below can help identify whether it’s a server response, client request, or core validation problem.

• Environment: Operating system, full client version, and the actual core name and version.
• Time and action: Date and time zone when the failure occurred, and whether it was the first import, a manual update, or an automatic update.
• Error: The first relevant log entry, HTTP status code, parse line number, and redacted surrounding context.
• Comparison: Results of direct versus proxied updates, and whether other subscriptions work.
• Config processing: Whether overrides, merge scripts, proxy providers, or rule providers are enabled.