Clash Subscription Not Working or Config Parsing Failed: Common Causes and Recovery Steps

When a Clash subscription update fails, common messages include request timeout, unexpected status codes, empty downloads, configuration parse errors, zero proxy nodes, and an immediate rollback after switching configurations. They may all look like “the subscription is unusable,” but they point to different failure layers. A subscription update passes through at least six stages: requesting the URL, receiving the server response, converting the content, parsing YAML, storing the configuration, and loading it into the core. Repeatedly clicking Update usually just triggers the same error again.

First identify which layer failed, then decide whether to replace the URL, regenerate the subscription, fix the configuration, or clear the client cache. Do not delete all data before saving the old configuration. Subscription URLs may contain access credentials and should never be copied directly into public logs, screenshots, or forum posts.

Identify the failed stage of the subscription update

The first step is not editing YAML; it is reading the first error in the client log. Later errors are often cascading results—for example, “configuration file not found” after a download failure, or “core startup failed” after a YAML parse error. Record the time, subscription name, HTTP status, error line number, and core type in use, then classify the issue by the following symptoms.

If manually selecting an older configuration restores connectivity, the core and local network are probably working; the issue is more likely in the subscription request or the new configuration content. If every configuration fails at once, also check the system clock, network path, DNS, system proxy loopback, and firewall. This prevents an environmental problem from being misdiagnosed as an expired subscription.

Check the subscription URL, expiry, and request conditions

A subscription URL is usually not an ordinary public web link. Its path or query parameters may identify the user, indicate plan status, and authorize access. If the server disables an old credential, the user regenerates the URL, the plan expires, or the subscription endpoint moves, the old URL may still open while returning only an error message.

Make sure the URL is complete

When copying a long link from a chat app, email, or QR code, it is easy to copy only the visible portion and omit trailing parameters. Line breaks, full-width punctuation, or leading and trailing spaces can also be introduced. Paste the complete URL again in the client’s subscription editor and confirm that the scheme, domain, path, and query string are all present without breaks. Do not manually remove parameters that look unnecessary; they may be required for server authentication or client-type detection.

Use the HTTP status to narrow down the cause

• 401 or 403: The access credential may have expired, permissions may be insufficient, or the server may have rejected the request. First retrieve a new URL from the subscription provider’s management page.
• 404: The old endpoint may have moved, the copied path may be incomplete, or the server may have removed the resource.
• 429: Too many requests were made in a short period. Stop refreshing repeatedly and test again after the rate limit is lifted.
• 5xx: The server or an upstream conversion service is temporarily unavailable. Deleting the local configuration usually will not help; keep the old configuration and try again later.
• 301 or 302: A redirect is not necessarily an error, but a redirect to a login page, announcement page, or different protocol may prevent the client from receiving the final subscription content.

Being able to open the URL in a browser does not mean the client can update successfully. A browser may retain a login session, follow redirects automatically, or display a server-generated information page, while a Clash client usually just sends a request and reads the response body. Conversely, seeing an unreadable block of encoded text in a browser does not necessarily mean the content is corrupted; some subscriptions are Base64-encoded collections of node links.

Check the system clock and network path

A significantly incorrect device date, time, or time zone can cause HTTPS certificate validation to fail. Enable automatic time synchronization first, then request the subscription again. If the current network blocks the subscription domain, temporarily switch to another trusted network and update once. When a system proxy is used to update the subscription, check for a loop: the client requests the subscription, but the traffic is sent to a local proxy port that has not started or is no longer working, resulting in connection refusal or a timeout.

How to identify a successful request with invalid content

HTTP 200 only means that the server returned content; it does not prove that the content is a valid configuration. Many parse failures are caused by an HTML page, a JSON error object, an empty response, or an incompatible subscription format returned by the server. Logs may report “proxies field not found,” “cannot parse mapping,” “illegal character,” or a syntax error near the first line.

Distinguish common subscription formats

Clash configurations typically use YAML, with common top-level fields including proxies, proxy-groups, rules, proxy-providers, and rule-providers. mihomo supports and extends some of these fields, but the available options still depend on the core version. Another common subscription format is plain text containing multiple protocol links, sometimes Base64-encoded. The client or a subscription converter must turn this content into a Clash configuration first; it should not be assumed to be complete YAML.

If the response body begins with HTML markup or is clearly a login notice, expired-plan message, or CAPTCHA page, the problem is in the server response—not the local YAML. Do not keep editing the YAML. For a JSON response, first check whether it contains an error code and message. If the response contains only a few characters or is completely empty, retrieve the subscription URL again and check the service status.

Check client and core compatibility

The same configuration can behave differently across clients. The traditional Clash core, Clash Meta (now generally maintained under the mihomo name), and different versions of graphical clients do not provide identical support for protocols, DNS fields, rule-set behavior, or configuration extensions. If the server generates fields supported only by a newer mihomo core while the client still uses an older core, you may see unknown fields, unsupported proxy types, or startup validation failures.

Open the client’s About page to confirm both the graphical interface version and the actual core version, then check the format required by the subscription provider. If the client supports switching cores, save the old configuration and follow its documentation to complete the switch. If the target fields are unsupported, choose a compatible subscription format instead of deleting unknown fields at random. Some fields depend on one another, so removing one may invalidate policy-group or rule references.

Locate YAML configuration parse failures

YAML is sensitive to indentation and data types. When the log gives a line number, inspect that line and the preceding few lines as well: the real error may be a missing quote in the previous section, a broken indentation level, or a misplaced list marker. Copy the original file before editing, use a plain-text editor, and keep the file encoded as UTF-8.

Indentation, tabs, and colons

Use spaces for indentation and never mix in tabs. Items at the same list level must use the same indentation. Node names, policy-group names, or string values containing special characters can be quoted, especially when a value contains a colon followed by a space, a hash sign, or another character YAML may interpret.

proxies:
  - name: "Tokyo: Primary"
    type: socks5
    server: 192.0.2.10
    port: 1080

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - "Tokyo: Primary"
      - DIRECT

rules:
  - MATCH,PROXY

This example is for structure only: proxies, proxy-groups, and rules are top-level fields; each list item begins with a hyphen; and node names referenced by a policy group must exactly match their definitions. Real proxy protocols also require the appropriate authentication, transport, and encryption parameters, so the example fields alone do not constitute a usable node.

Check field types

Ports should normally be numbers, Boolean values must use a Boolean type recognized by the core, and list fields cannot be written as ordinary strings. Common mistakes include writing proxies as a single-line string, writing a rule list as an object, adding units where a number is expected, and omitting quotes so that numbers or special values are interpreted incorrectly. When the parser says “expected sequence,” it usually needs a list; “expected mapping” usually means that position should contain a key-value structure.

Check name references and fallback rules

Configurations connect nodes, policy groups, and rules by name. A policy group that references a deleted or renamed node, or a rule that references a nonexistent policy group, can make validation fail or produce unexpected behavior. Names usually must match exactly, including capitalization, spaces, and symbols. Rules should progress from specific matches to a fallback; MATCH generally belongs at the end of the rule list. A fallback placed too early prevents later rules from being reached.

Do not treat a partial subscription as a complete configuration

The content returned by proxy-providers may be only a collection of proxies, loaded by provider entries in the main configuration. It may not include ports, DNS, policy groups, or complete rules, so it cannot always be imported as a standalone main configuration. Likewise, a remote rule set supplies only domain, IP, or rule-behavior data; it is not a bootable Clash configuration. Make sure you copied the main subscription endpoint rather than a provider or rule-set URL.

Handle client cache, old configurations, and write failures

If the subscription response is correct and the configuration passes an independent check but the client still shows old nodes, investigate the cache and storage layers. Graphical clients commonly maintain a subscription index, downloaded configuration copies, the active configuration, and core runtime files. The subscription name shown in the interface may also differ from the filename on disk.

1. Stop automatic updates: Temporarily disable frequent scheduled refreshes so the files are not continually overwritten during diagnosis.
2. Export the current configuration: Save working nodes, policy-group selections, and local overrides, and record the current configuration name.
3. Create a new subscription entry: Do not overwrite the old entry immediately. Use the newly retrieved URL to create a separate entry and update it.
4. Check the update time: Confirm that the client’s displayed update time, node count, and log timestamp match this operation.
5. Validate the configuration: Use the client’s validation feature before switching, and confirm that the current core can load the new configuration.
6. Switch and restart the core: Restart only the proxy core or client; there is no need to reboot the entire system first. Confirm that the new configuration actually becomes active.
7. Delete the old entry only after stability is confirmed: Keep a rollback version until rules, DNS, and proxy connectivity have all been verified.

If the file timestamp does not change after an update, check whether the configuration directory is writable, whether sufficient disk space is available, and whether security software is blocking writes. When the client is installed in a protected system directory, ordinary permissions may prevent it from updating nearby configuration files. A properly designed client generally stores user data in the user profile directory; use the client log to confirm the actual path.

Do not delete the entire user-data directory without a backup. It may contain subscription URLs, override rules, policy-group selections, DNS settings, and interface preferences. A safer approach is to export the configuration first, then use the client documentation to locate the specific subscription cache or index. If the client offers a “reset configuration” function, understand its scope before using it.

The subscription imports, but nodes or rule sets are empty

A successful import does not mean that every remote resource has loaded. The main configuration may still reference proxy-providers and rule-providers, which the core requests separately after startup. The main subscription can return normally while an expired provider URL leaves the interface with empty policy groups, failed rule-set downloads, or missing nodes.

Check proxy-provider updates

Review the provider name, request status, and update time in the log. When a policy group uses use to reference a provider, the provider name must match its definition exactly. Remote content must use the provider format required by the core; an ordinary web page, a complete main configuration, or an incompatible node list can all fail to load. If a policy group uses both static proxies and a provider, the static entries may still appear and hide the remote collection failure.

Check remote rule sets

The rule set’s behavior, content format, and rule type must correspond. For example, domain, ipcidr, and classical behaviors use different data structures. Any mismatch among the rule-set name referenced by the main configuration, the policy name in the rules, and the remote file format can make the rule set unusable. After updating, check the log for a rule count and confirm that a fallback such as MATCH is present.

Consider the direct and proxied download paths

Remote resources may be fetched directly or through the active proxy. If a provider is reachable only through a proxy but the core has no usable node before loading the provider, startup can become circularly dependent. Conversely, if the server permits direct access only from a specific network, forcing the request through a proxy will also fail. Choose the download path supported by the client and core, and keep at least one viable startup route.

Post-recovery verification checklist

After the subscription update button reports success, verify that the configuration is actually running. Checking only the node list is not enough, because DNS, rules, and the system proxy may still be using old state. Complete the following tests in a consistent order.

• Confirm that the subscription update time, configuration file modification time, and log time match.
• Confirm that the node count is as expected and that policy groups do not contain widespread empty references.
• Run a latency test against one node; the result shows only that the test address is reachable, not that every website is accessible.
• Check the current proxy mode and confirm that rule, global, or direct mode matches the test objective.
• Open the connection log and confirm that the target request matched the expected rule and policy group.
• Check the DNS log for failed resolution, incorrect mappings, or DNS bypass by the operating system.
• When system proxying is enabled, confirm that the local listening port matches the system settings. With TUN enabled, confirm that the service, permissions, and routes are established.
• Restart the client once and confirm that the subscription index and active configuration persist instead of working only for the current session.

TUN mode takes over a broader range of system traffic, but it cannot repair an invalid subscription or malformed YAML. Do not treat enabling TUN as a recovery method before the configuration passes validation. Conversely, if the configuration is sound and only some applications bypass the proxy, check TUN permissions, system routes, exclusions, and the applications’ own proxy settings.

Choose a recovery action by symptom

The complete recovery sequence can be summarized as follows: read the first error, then confirm the request status; after a successful request, identify the response content; once the content is correct, check YAML and core compatibility; after validation passes, handle caching and writes; finally verify providers, rules, DNS, the system proxy, or TUN. Working layer by layer preserves usable configurations and prevents accidental deletion of local working versions while the subscription service is experiencing an outage.