The four stages
- Request — the client could not reach the address at all: timeout, connection refused, DNS failure.
- Response — the server answered with a status that is not a usable payload: 401, 403, 429, 5xx, or a redirect to a login page.
- Parse — bytes arrived but do not form the expected document: HTML instead of YAML, a Base64 blob where a profile was expected, truncated content.
- Load — parsing succeeded but the profile is incomplete or the core rejects it: no
proxies, noproxy-providers, an unsupported field, a port conflict.
Each stage has different owners. Stage one belongs to your network or the provider's reachability; stage two to credentials, plan state or rate limits; stage three to the format the address returns; stage four to the client, the core and the configuration. Collapsing all four into “the subscription is dead” guarantees you will fix the wrong thing.
Save the original error first
“Timeout”, “connection failed” and “invalid subscription content” are three different messages. When you capture a screenshot, keep the error text, the time and the client version, and mask the full link and token. Do not delete all configurations first: the old profile may still be the only working state, and deleting it also removes your comparison baseline.
Same wording, different branch
Clash Verge Rev's remote-profile parsing makes the split concrete. A non-success HTTP status returns a fetch error before any parsing happens. A body that cannot be parsed into a YAML mapping returns the remote profile data is invalid yaml. A YAML document that parses but has no top-level proxies or proxy-providers returns a different missing-field error. One screenshot captioned “update failed” can therefore require three different checks, and none of them is “the provider went out of business”.
| First clear error | Minimum evidence to keep | First action |
|---|---|---|
| Timeout, connection refused, HTTP 401/403/429/5xx | Time, status code, whether the provider panel can issue a new link | Check network, credentials, rate limits or service state — do not edit YAML yet |
the remote profile data is invalid yaml | Client version, masked error, the content type you observed locally | Confirm the body is a Clash/Mihomo profile and not HTML, Base64 or partial YAML |
Missing proxies or proxy-providers | Top-level key names, the format the provider says it is serving | Check whether you imported the wrong format or a profile that genuinely lacks those keys |
| Update reported success, proxy list empty | Active profile, provider state, proxy-group references | Check whether main config and provider are fetched and loaded separately |
Names differ by client and version. The table is a routing aid, not a universal error-code dictionary.
Evidence table: where the failure sits
| Symptom | Save this first | Check first | Not established |
|---|---|---|---|
| Timeout, cannot connect | Time, network, update method, log text | Local network, current proxy path, service state | That the subscription is revoked |
| 401 / 403 | Status code, whether a fresh link can be copied from the panel | Token, permissions, access restriction | That the provider has stopped operating |
| 429 | Retry-After, time, number of attempts | The wait window and the provider's rate-limit note | That refreshing faster will help |
| 200 but zero nodes | Content type, body length, whether it is HTML | What the body actually is, and client format support | That a 200 means a valid subscription |
| Nodes appear, core fails | Core log, versions, config fields | Core compatibility, fields, ports, files | That this is a download problem at all |
Is the address even the right one
Confirm you copied the subscription address the provider issued, not a login, purchase or help page. Watch for a stray space, a missing character or a token that has already been reset. The format the client expects should also match what the provider documents.
Subscription addresses usually contain a usable credential. Never publish the full URL, a QR code or a token while troubleshooting; if it leaked, rotate it in the provider panel rather than deleting a screenshot.
When the request itself fails
Check the base network and the plan state first, then look at whether the client lets you choose how the update is fetched. Some clients can update directly, through the current proxy, or through the system proxy — and those paths depend on different networks.
Change only the update method, and record: client and version, OS, time with time zone, the original method and the comparison method, the HTTP status or error text, whether every network fails, and whether only this one subscription fails.
- A dead node makes “update through the proxy” time out.
- A server that restricts some sources makes “update directly” fail.
Either result narrows the range. Neither assigns responsibility without the log.
401 and 403 specifically
- 401 usually means the address did not authenticate: reset token, wrong path, or a link from a different account.
- 403 usually means the request authenticated but was refused: plan expired, device limit, region block, or a gateway rule.
- In both cases, copy a fresh address from the panel before touching anything else. If a new address works, the old one was stale — record the difference rather than assuming an outage.
- If a fresh address fails the same way, the provider side needs to answer. Do not upload the URL to a public checker to find out.
429 and 5xx
A 429 is a rate limit, and the useful evidence is the retry window plus how many times you pressed update. A burst of retries usually extends the block. A 5xx is the server's own failure; the useful evidence is the timestamp and whether the provider reports an incident. Neither is repaired by editing YAML or switching nodes.
200 with an empty or wrong body
This is the most misread case. The request completed; the payload is not what you expected. Check on your own device:
- Is the content type what the provider claims?
- Does the first line look like a profile, a Base64 blob, or
<!DOCTYPE html>? - Does the body length look plausible for the number of nodes?
- Was the response compressed in a way the client did not decode?
If the provider offers several formats, change the format once and repeat the same action. Do not change client, format and network simultaneously.
After a successful update, verify
- The profile card exists and is the active configuration.
- The proxy list contains the expected entries, and groups reference nodes that exist.
- The core started without an error.
- One ordinary HTTPS request succeeds through the intended path.
If the provider's content was not supposed to change, an unchanged list is a correct outcome, not a failure. Only compare node, group and field differences when the server-side content was expected to change.
What to report
- Client and version, OS, entry point used.
- Time with time zone, and the exact first error text.
- HTTP status if one was visible, and whether a fresh address from the panel behaves differently.
- Update method used, and the single-variable comparison result.
- Masked URL: scheme, domain, and a masked path only.