On this page
When a Clash Subscription Import Fails, Distinguish an Expired Link from an Unreadable Format
Clients often reduce “update failed” to one notification, but an expired link, Invalid YAML, and an unsupported field require entirely different responses. Preserve the exact error, HTTP status, and line number; determine the failing stage before using a YAML editor on what is actually a sign-in page.
Evidence for the two failure classes
| Behavior | Description | What to do first |
|---|---|---|
| HTTP 401, 403, 404, or a timeout | The remote request has not returned a usable configuration | Check the token, address, network, and server status |
| The response is HTML, a sign-in page, or a plan notice | The URL is reachable, but the content is not YAML | Confirm that you copied the subscription endpoint rather than a web-page address |
| mapping values are not allowed | YAML structure or indentation is invalid | Locate the problem from the reported line and its parent indentation |
| unknown field、cannot unmarshal | The syntax may be valid, but the current core rejects the field or data type | Check the core version and official field documentation |
Inspect response headers and the opening content without exposing the full subscription address
Inspect the subscription response only in a terminal or browser developer tools you control. The status should indicate success, and the body should begin like a YAML configuration or provider data—not <!DOCTYPE html>, a sign-in form, a JSON error, or a “traffic quota exhausted” notice.
A subscription URL often contains a token that directly retrieves the configuration. Redact query parameters from screenshots, and do not paste the curl command into a public ticket. If the link has already been exposed, reset it in the service panel before continuing to investigate the old response.
# URL 中含私密 token，不要复制输出到公开位置
curl -I "https://example.invalid/subscription?token=REDACTED"
curl -sS "https://example.invalid/subscription?token=REDACTED" | headA reported YAML line is often only where an already-broken parent structure becomes visible
YAML expresses hierarchy through indentation. A Tab, missing colon, unclosed quote, or malformed list marker may cause the parser to report the next line. If it reports line 48 column 7, inspect not only line 48 but also its parent key and whether the previous item ended.
Quote proxy names containing a colon, number sign, or special character. Do not mix different indentation widths at the same level. Edit a copy and preserve the original file; correct one error at a time and retest before moving to the next.
# 正确：proxies 是列表
proxy-groups:
- name: PROXY
type: select
proxies:
- DIRECT
# 错误：proxies 被写成普通字符串
proxy-groups:
- name: PROXY
type: select
proxies: DIRECTValid YAML does not mean Mihomo accepts the fields
A general-purpose YAML checker validates only text structure; it does not know Mihomo's fields, types, or references. An unknown field, proxy not found, group not found, or unsupported protocol means you must return to the current core's version and documentation instead of adjusting indentation again.
The core bundled with the client may lag behind the subscription generator, or a merge override may move a field to the wrong location. First identify the actual core in “About” or the startup log, then compare against current Mihomo documentation. Preserve a working configuration before upgrading so a protocol-compatibility issue does not become a new migration problem.
A complete configuration, node Provider, and rule set are not interchangeable
A complete configuration typically includes ports, proxy groups, and rules. A proxy-provider file mainly supplies nodes, while a rule-provider file supplies rule content according to a behavior such as domain, ipcidr, or classical.
If you import a provider URL as a complete subscription, the client will report missing required configuration fields even when the file itself is valid YAML.
Conversely, putting a complete configuration under proxy-providers may fail while parsing the list. Inspect the returned top-level keys and the provider's documented import method before deciding whether it belongs in a Profile, proxy-providers, or rule-providers.
- Complete Profile
- Usually loads independently and contains runtime configuration such as proxy-groups and rules.
- Proxy Provider
- Referenced from the main configuration through proxy-providers; its content focuses on the node list.
- Rule Provider
- Used by RULE-SET; behavior must correspond to the payload structure.
Test in a copy, and inspect the final file after the client merges it
First save a copy of the original response, then redact the token and node credentials before editing. The Mihomo command line can test a configuration in a specified directory, and graphical clients also typically validate before loading. Start with the first error emitted by the core actually in use.
If the original file passes but the client still fails, inspect the final configuration generated by Merge, Mixin, override scripts, or global settings. The subscription itself is often valid; an override may reference a deleted policy group or generate two incompatible versions of the same top-level key.
The original subscription is readable, but the final configuration reports group not found
Common cause:An override or old rule references a policy group that no longer exists
Resolution:Search for the group name in the final configuration and temporarily disable the related override.
The subscription is HTML
Common cause:A web page was copied, sign-in expired, or the token is invalid
Resolution:Obtain a dedicated subscription address again; do not edit the HTML.
A Provider update fails on its own
Common cause:A problem with URL, path, behavior, or write permission
Resolution:Check according to the provider type instead of rebuilding the entire Profile.
First restore a configuration that loads, then organize the cause of the error
When the active configuration is damaged, switch back to the previous working Profile or a clean subscription regenerated by the provider so the network recovers. Do not repeatedly hand-edit the only production configuration, and do not configure a file that fails parsing to load automatically at startup.
Keep at least the failure stage, original error, client and core versions, and corrective action in the repair notes. If the same subscription fails again after a later update, this evidence distinguishes a server-side generation change, a client upgrade, and a local override reintroducing the error.