Clash Subscription Import Failed? Fix Parse Errors and YAML Issues

First, tell a failed subscription download from a failed configuration load

A “subscription import failed” error can happen at several stages: the client may not receive a response, the server may return an error page, the configuration may fail to parse, or the running core may not support a protocol in the configuration. Only the last case calls for a closer look at core compatibility. Switching proxies repeatedly usually won’t fix the first three issues.

FlClash uses the mihomo core. The client manages subscriptions, the interface, and configuration processing; the core validates configurations and routes traffic. When the interface shows “Update failed,” check both the update error details and whether a core-loading error follows. Menu labels can vary by version, so the steps below refer to features rather than treating one version’s menu path as universal across platforms.

Save three things before troubleshooting

1. Note the FlClash version, operating system, and core version actually in use. Core updates don’t necessarily coincide with client updates, so “latest version” alone isn’t enough.
2. Keep logs from around the failure—for example, the 30 seconds before and after the update—to distinguish download, parsing, and loading issues.
3. Back up any configuration that still works. Import into a new test profile rather than immediately overwriting your only working configuration file.

Subscription URLs often contain access tokens. Before sharing screenshots, logs, or configuration files, remove credentials from URL query parameters and redact proxy passwords, UUIDs, authorization headers, and personal paths. Hiding only the domain does not protect access to the subscription.

Layer 1: Check URL reachability and HTTP status

Check the URL first, then test the network

Copy the Clash- or mihomo-compatible subscription URL again from your provider’s account page. Check that it starts with https:// and that no spaces, line breaks, quotes, or punctuation have been added at the end. An account login page, plan details page, or QR-code image URL is not a subscription URL. Decode a QR code to get the actual link; don’t import the image file into the client.

If a link opens in your browser, that only confirms the browser’s request worked at that moment. The browser may have sent a login cookie or used a different proxy route from the client. Background subscription updates usually don’t inherit the browser’s login session. Test the client update and a separate download independently; they may use different network paths.

Make a limited download request to inspect the response

On macOS or Linux, you can run the following command in a Bash terminal. It reads the URL without displaying it, so it won’t be written directly into your command history. The response body is saved in the current directory instead of being printed in the terminal; use a temporary working directory that only you can access.

read -r -s -p 'Enter subscription URL: ' SUB_URL
printf '\n'
curl --location --max-redirs 3 \
  --proto '=https' --proto-redir '=https' \
  --connect-timeout 10 --max-time 30 \
  --output subscription-response.txt \
  --write-out 'HTTP %{http_code}\nType %{content_type}\nBytes %{size_download}\n' \
  "$SUB_URL"
unset SUB_URL

This command uses a 10-second connection timeout, a 30-second total timeout, a maximum of 3 redirects, and HTTPS only. These are diagnostic settings for this request, not FlClash defaults. In Windows PowerShell, you can use curl.exe with the same options; don’t copy Bash’s read command or line-continuation syntax directly.

• HTTP 200: The server returned a successful status, but you still need to inspect the response body. Login and error pages can also return 200.
• HTTP 301/302: Check that the redirect destination still belongs to the expected service. Don’t publicly share the full redirect URL if it contains a token.
• HTTP 401/403: Check whether the token was reset, the plan is active, and the account has any access restrictions. A 403 can also come from a security service.
• HTTP 404/410: First check whether the URL has expired or the endpoint has moved. Don’t try to restore access by guessing a different path.
• HTTP 429: Stop repeated refresh attempts and wait as directed by the server. Automated retries may extend the rate limit.
• HTTP 5xx: Note the time and status code, try again later, and contact the provider. Editing local YAML won’t fix a server-side error.

If the result is HTTP 000, no reportable HTTP status was received; the server did not actually return “000.” Check the curl error for DNS, connection timeout, or TLS certificate issues. For certificate errors, first check the device clock, certificate validity, and possible network interception. Don’t bypass the issue long-term by disabling certificate verification.

Avoid creating a dependency loop for subscription updates

If the subscription domain requires a proxy but no usable configuration is available, the first update may fail. Conversely, if the subscription service blocks your proxy’s exit IP, a direct connection may work better. Check whether the client offers a proxy setting or download policy for subscription updates. Change one route at a time and record the result. TUN mode is not a fix for parse errors; don’t switch TUN, DNS, and the subscription URL all at once.

Layer 2: Make sure the response is a configuration, not a web page or another subscription format

Open subscription-response.txt in a local text editor and inspect it only on your own device. Content-Type can offer a clue, but servers may use text/plain or a generic download type, so the response header alone can’t confirm the content is valid.

A full configuration is also different from a proxy provider file. A file containing only proxies: may be intended for proxy-providers; it may not include the proxy groups and rules the client needs. A file containing only payload: is usually a rule set, not a proxy subscription. Import behavior depends on whether the client adds a template, so being valid YAML doesn’t necessarily mean a file can run as a complete configuration.

Some services return different formats based on the request’s User-Agent. If the same URL returns different content in a browser and the client, ask the provider which endpoint and format to use rather than blindly spoofing request headers. If you need to convert the format, prefer a provider-supported option or a conversion tool you control. Sending a full subscription to a public converter also gives it access to the credentials in that subscription.

Layer 3: Check YAML syntax, field types, and name references

The reported line marks where the error was found, not necessarily where it began

yaml: line 12 means the parser found a problem near line 12. The actual cause may be on the previous line, such as an unclosed quote or changed parent indentation. Inspect the five lines before and after the reported line; don’t delete the entire proxy list.

• Use spaces, not tabs, for indentation. Keep indentation consistent at each level—for example, two spaces per level.
• Use a standard colon in mapping fields, usually followed by a space, as in mode: rule.
• Use a standard - for list items and make sure it’s under the correct field.
• Quote names, passwords, and URLs containing : , #, or complex symbols. Escaping rules still apply inside quotes.
• Port fields should be integers, and proxies should be a list. YAML can be syntactically valid but still fail during configuration decoding if a field has the wrong type.

Isolate syntax issues with a minimal configuration

The minimal configuration below is for isolating issues and connects directly; it contains no proxy nodes. The mixed port is set to 17890 for this example only. Before using it, make sure no other process is using that port. This configuration does not provide proxy connectivity.

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

proxies: []

proxy-groups:
  - name: "Diagnostic Exit"
    type: select
    proxies:
      - DIRECT

rules:
  - MATCH,Diagnostic Exit

If the minimal configuration validates but the original subscription doesn’t, focus on the original file and the configuration merge process. If you still get a port-in-use or permission error, you’re dealing with a runtime environment issue, not a YAML syntax error. A direct connection with this configuration also doesn’t prove that any proxy node works.

If mihomo is installed locally, run mihomo -t -f ./subscription-response.txt in a terminal to check the configuration. This command uses the core found by your current terminal, which may differ from the version bundled with FlClash. Checking some provider configurations may also access external resources, so run the test in a controlled local environment. Passing the check doesn’t mean every proxy node is reachable.

Check proxy groups, rules, and the final merged configuration

If the error says a proxy name can’t be found, compare the node name and proxy group reference character by character, including spaces and capitalization. The outbound name at the end of a rule must point to an existing node, proxy group, or built-in outbound. Names referenced through use must match keys under proxy-providers; a provider name can’t be used as a regular proxy reference.

If the original subscription passes validation but the client fails to load it, check client overrides, merged configuration, and proxy filters. A filter expression may remove every candidate node, while a rename may leave old references behind. First disable custom processing in a test profile, then restore settings one at a time. Direct edits to the subscription cache are usually overwritten at the next update.

Layer 4: Check proxy protocol support and the core actually in use

Using the Clash configuration format doesn’t mean every Clash client supports the same protocols. Traditional Clash, mihomo, and core versions from different releases may support different protocols and fields. For an unsupported proxy type error, note the reported type value first, then check the core version and release notes.

1. Check the protocol name. For example, a node with type: hysteria2 requires a core that supports that protocol; changing the type to ss won’t make it work.
2. Check required fields and data types. Review fields such as server, port, password, and UUID. Requirements vary by protocol.
3. Check transport and TLS settings. The server address, SNI, WebSocket path, and related options must match the server. A configuration that parses successfully doesn’t guarantee a valid handshake.
4. Check whether fields are recognized. Some unknown fields may be ignored rather than reported as errors. “Import successful” alone doesn’t prove that every option took effect.
5. Use a compatible subscription format. If the provider offers a mihomo-compatible format, choose it. Before upgrading, back up your configuration, then update the client or core.

If import succeeds but you get a dial timeout, authentication failure, or TLS handshake error, the problem has moved to the connection stage. Check proxy reachability, credentials, and server settings instead of adjusting YAML indentation. Successful parsing, core startup, proxy connectivity, and application access are four separate checks.

Verification steps and what to include in a report

Test one stage at a time

1. Manually update the subscription once. Confirm that the response isn’t empty and that no HTTP or download error appears.
2. Load the test configuration and check the logs for YAML, protocol type, or name reference errors.
3. Confirm the core keeps running without port conflicts, permission errors, or provider resource loading failures.
4. Test the connection with a proxy node you’ve confirmed exists, then use the target application to verify which outbound the rules select.
5. Restore the overrides and filters you need, checking them one at a time. Restore scheduled updates last.

When contacting the provider or project team, include your operating system, client version, core version, failure time, HTTP status code, and the first relevant error with sensitive details redacted. For YAML issues, include the smallest snippet around the reported line. For download issues, describe the results over both the direct and current proxy routes. Don’t send the full subscription file with credentials.

If a subscription URL has been exposed in a public screenshot, support ticket, or conversion service, reset its token in your provider account and update it on all your devices. Deleting local records can’t revoke access that has already been exposed.

Follow this order: “URL access → response format → YAML and references → core compatibility.” This avoids repeatedly changing ports when the server is returning a login page, and prevents a proxy connection timeout from being mistaken for a subscription format error. See the configuration field reference for common field definitions. For steps to enable the system proxy and TUN for the first time, see Getting Started.