Clash Subscription Not Working or Parsing Failed? A Step-by-Step Troubleshooting Checklist

First distinguish download, parsing, and configuration-loading failures

When the client shows “Update failed,” the problem may occur at one of three stages. First, the subscription is fetched over HTTPS. Next, the response is identified as YAML, a Base64 node list, or another format. Finally, the parsed configuration is passed to the Clash Meta (mihomo) core for loading. The interface messages can look similar, but each stage requires a different diagnostic approach.

Record the complete error message, time of occurrence, and current client version first. Then open the client logs and temporarily set the log level to “Info” or “Debug.” In Clash Verge Rev 2.x, for example, go to Settings → Logs; other clients may use slightly different labels or place the option under Settings → Diagnostics. Restore the normal log level after troubleshooting to avoid accumulating excessive logs.

Step 1: Verify that the subscription URL returns content

Check the HTTP status code and redirect chain

Opening the subscription URL in a browser private window is only a preliminary check. Browsers may send cookies automatically, follow redirects, or display a downloaded file, while the client uses an independent network request. A more reliable method is to inspect the final status code and response headers. On Windows 11, run the command below in PowerShell; on macOS and Linux, use the system curl or a locally installed version.

curl -L --max-redirs 5 --connect-timeout 10 \
  --max-time 30 -D headers.txt \
  -o subscription.txt \
  "https://example.com/api/subscription?token=REDACTED"

-L follows 301, 302, 307, and 308 redirects; --max-redirs 5 limits the number of redirects; the connection timeout is 10 seconds and the total request timeout is 30 seconds. The command saves response headers to headers.txt and the body to subscription.txt. Replace the example address locally when testing; never put a real token in a shared script.

• 200: The server returned content. Continue by checking whether the body is actually a subscription configuration.
• 301, 302, 307, 308: A redirect is present. If the final response is still a redirect, it may be looping; if it leads to a login page, the client cannot complete an interactive login.
• 401, 403: The token may be expired, permissions may be insufficient, the source may be restricted, or the request may have been blocked by policy.
• 404, 410: The subscription path was revoked, the old address was retired after a plan migration, or the URL was truncated during copying.
• 429: Too many requests. Pause automatic refreshes and try again after the server’s rate-limit window ends.
• 500, 502, 503, 504: The server or an upstream service is temporarily unavailable. Check the service status and whether a later retry succeeds.

Check whether the URL changed while being copied

Subscription addresses often contain ?, &, =, and %. Line wrapping in chat apps, escaping by rich-text editors, or manually deleting a trailing character can invalidate the token. The address should not have quotation marks, full-width spaces, or line breaks around it. If the provider’s dashboard has a “Copy subscription” button, copy the complete address again and create a new configuration in the client instead of continuing to edit the old entry.

Also check the system clock. HTTPS certificate validation depends on the local time; a date offset of several days can produce errors saying that a certificate is not yet valid or has expired. On Windows, go to Settings → Time & language → Date & time, enable automatic time setting, and sync immediately. On Android, the option is usually under Settings → System → Date & time.

Rule out system-proxy loops and current-node failures

Subscription requests may use a direct connection or inherit the system proxy. A common local mixed port is 7890, while some clients default to 7897; use the Mixed Port value shown under Settings → Port settings as the source of truth. If the client core has stopped while the system proxy still points to 127.0.0.1:7890, the request will connect to a local port with no listener.

1. Turn off the “System Proxy” option in the client, then try updating the subscription again.
2. If the subscription domain is unreachable directly, restart the core, select a confirmed working node, and update again.
3. If TUN mode is enabled, turn it off under Settings → Network settings and make one ordinary request for comparison.
4. Check whether the logs contain connection refused 127.0.0.1, i/o timeout, or repeated forwarding to a local port.

TUN mode does not parse YAML syntax itself, but it changes the route used for subscription requests. Only if the update succeeds after TUN is disabled should you check route exclusions, system-proxy status, and current-node availability; do not edit the subscription body first.

Step 2: Confirm that the response is a usable subscription

Inspect the beginning of the body, not just the file extension

It is common for a subscription URL not to end in .yaml; judge it by the response content instead. Open the saved subscription.txt in a text editor and inspect the first 20 lines. A complete YAML configuration for Clash or mihomo usually includes top-level fields such as proxies, proxy-groups, rules, or proxy-providers.

mixed-port: 7890
mode: rule

proxies:
  - name: "Example Node"
    type: ss
    server: 203.0.113.10
    port: 443

proxy-groups:
  - name: "PROXY"
    type: select
    proxies:
      - "Example Node"

rules:
  - MATCH,PROXY

If the body begins with <!doctype html>, <html>, or a login form, you received a web page rather than a configuration. A JSON error object such as {"code":403,"message":"expired"} is not a Clash configuration either. Resolve the authorization or server-side issue; editing the YAML file will not help.

Identify Base64 node lists and share links

A long string containing only letters, numbers, plus signs, slashes, and equals signs may be a Base64-encoded universal subscription. After decoding, it commonly contains one link per line, such as ss://, trojan://, vmess://, or hysteria2://. Some clients can import these links, but loading them as a complete Clash YAML file produces a top-level type error or a missing proxies field.

First return to the subscription provider’s dashboard and choose an output format labeled Clash, Clash Meta, or mihomo. Format conversion exposes node credentials, so use a local tool you control or a trusted server-side API. After conversion, still inspect proxy groups, rules, and DNS settings: a node list describes connection parameters only and is not a complete routing configuration.

Check the character encoding and file header

Save YAML files as UTF-8. If the editor shows widespread garbled text or the logs report control-character errors, export the file again as UTF-8. A UTF-8 BOM is normally handled by modern parsers, but some older clients or wrapper conversion scripts may treat it as part of a field. During troubleshooting, save a new UTF-8 copy and keep the original for comparison.

Step 3: Locate YAML syntax and structure errors line by line

Start with the line and column reported in the logs

Typical errors include did not find expected key, mapping values are not allowed, cannot unmarshal, and duplicate key. The line number usually points to where the parser finally lost the structure; the actual mistake may be one to three lines earlier. Check the reported line, the previous item’s indentation, and whether quotation marks are balanced.

• Use spaces for indentation; do not mix tabs and spaces.
• Keep indentation consistent at each level; two spaces per level is common.
• Leave a space after the hyphen for list items, for example - name: node-a.
• Quote names that contain colons, hash signs, braces, or leading or trailing spaces.
• Write ports as integers, such as port: 443; do not include extra text in the value.

# Incorrect: proxy-groups is indented inside the proxies item
proxies:
  - name: node-a
    type: ss
  proxy-groups:
    - name: PROXY

# Correct: both fields are at the top level
proxies:
  - name: node-a
    type: ss

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - node-a

Distinguish valid syntax from valid field types

Passing a YAML syntax check does not mean the core accepts every field. For example, port: "443" is a string in YAML, while protocol configuration usually requires an integer; udp: "true" is a string, while the expected value is the Boolean true. When the logs show cannot unmarshal string into Go value, focus on checking value types.

Check proxy-group references and rule targets

After syntax parsing succeeds, the core also validates references. The policy name at the end of a rule must match an existing proxy group, proxy name, or built-in action. For example, if a rule is DOMAIN-SUFFIX,example.com,Proxy but the configuration contains only a group named PROXY, the case difference makes the target unavailable. Node names in proxy groups must likewise match entries referenced from proxies or use.

When using RULE-SET, also confirm that the corresponding name is defined in rule-providers. The provider’s behavior must match its content: domain collections usually use domain, IP-range collections use ipcidr, and collections containing complete rule statements use classical. If a remote rule set fails to download, the main subscription may still have parsed successfully; the logs will separately show the provider URL, status code, or timeout.

Step 4: Check Clash Meta core versions and field compatibility

Treat the client UI version and core version as separate details

Desktop clients, mobile clients, and the mihomo core each have independent versions. Updating the interface does not necessarily update the core; different behavior on two devices often comes from different core versions. Record the full version information under Settings → About or Settings → Core. At minimum, note the client name, client version, core type, and core version, such as “Clash Verge Rev 2.x, mihomo 1.19.x.”

Newer protocols and transport fields depend on support in the corresponding core. If the configuration includes type: hysteria2, type: tuic, VLESS Reality, WireGuard, or newer DNS fields, an older Clash core may report an unknown type or field. Switch to the mihomo core required by the subscription, or have the provider output a format compatible with the current core; do not randomly delete authentication, TLS, or transport parameters.

Use a minimal configuration to determine whether the issue is a node or global configuration

After keeping a copy of the original file, create a minimal test configuration containing one known node, one proxy group, and one MATCH rule. If it loads, add DNS, TUN, rule-providers, and advanced protocol settings back section by section to isolate the problem. If a single node still fails, focus on its type, address, port, authentication fields, and TLS parameters.

mixed-port: 7890
mode: rule
log-level: info

proxies:
  - name: test-node
    type: socks5
    server: 127.0.0.1
    port: 1080

proxy-groups:
  - name: PROXY
    type: select
    proxies:
      - test-node
      - DIRECT

rules:
  - MATCH,PROXY

This example is only for verifying that the structure can load; 127.0.0.1:1080 must have an actual SOCKS5 service listening for a connection to succeed. If the structure test passes but the network test fails, the YAML framework is accepted by the core, so continue with node reachability and authentication parameters.

Check port usage and leftover core processes

If parsing succeeds but the logs show address already in use, the problem is a listening-port conflict, not the subscription format. Common conflicts include an old core still using 7890, another instance occupying the controller port 9090, or multiple clients enabling the system proxy at once. Fully exit other proxy clients and leftover core processes, then reload the configuration; you can also temporarily change Mixed Port to 7897 for comparison.

On Windows, run netstat -ano | findstr :7890 to find the process ID using the port; on macOS and Linux, run lsof -iTCP:7890 -sTCP:LISTEN. Confirm the process identity before terminating it; do not act on a system service based on the port number alone.

Step 5: Apply the appropriate fix based on the result

Expired link or authorization failure

1. Generate a new subscription URL from the service dashboard and confirm the plan status and device limits.
2. Delete the failed entry in the client and create a new subscription instead of continuing to use a cached URL.
3. Set the automatic update interval to a reasonable value, such as 1,440 minutes; repeated refreshes in a short period may trigger 429.
4. If the new link still returns 401 or 403, contact the provider with the status code, time, and logs containing a masked token.

Web page, JSON error, or generic node list returned

1. Confirm that you copied the subscription endpoint rather than the user-center page URL.
2. Select the Clash Meta or mihomo format and download the configuration again.
3. If you can obtain only a list of share links, use a local conversion workflow to generate YAML, then add proxy groups and rules yourself.
4. Import the converted file as a new configuration first; do not overwrite the old configuration that still works.

Incompatible YAML fields or core

1. Use the log line number to check indentation, quotation marks, and field types.
2. Compare the configuration structure supported by the current mihomo version and verify the protocol type and DNS fields.
3. Restore sections one at a time with a minimal configuration to isolate a single node, rule set, or DNS section.
4. Restart the client after updating the core, establish a new connection, and test again; do not rely on results from an old connection.

Verification record after the fix

A complete verification should cover four results: the subscription request returns 200; the body uses the expected format; the configuration loads into the mihomo core; and an actual connection follows the rules into the intended proxy group. Seeing the node count increase alone does not prove that rule sets, DNS, or TUN are working correctly.

• Refresh manually once and record the duration. For example, three consecutive attempts on the same network might take 1.2, 1.4, and 1.3 seconds; the results should be reasonably consistent.
• Open the logs, visit one direct domain and one proxied domain, and confirm that the matched rules point to the expected targets.
• After switching proxy groups, create a new connection; an existing TCP connection may continue using the previous exit.
• Restart the client and load the configuration once more to rule out temporary state that existed only in memory.
• Restore a suitable automatic update interval and confirm that the system-proxy and TUN states match your normal usage setup.

Keep the troubleshooting order fixed: check the HTTP status and response body first, then inspect YAML syntax and references, and finally handle core versions, ports, and runtime state. This prevents repeatedly editing a configuration when the link has already expired and avoids mistaking a port conflict for a subscription parsing error.