Node HandbookNODE HANDBOOK中文
Subscription · error stages

A subscription update failed: which of the four stages

Timeout, 401, 403, 429, an empty body and invalid content are not the same symptom. Split the failure into request, response, parse and load, and the next check stops being a guess.

Node Handbook editorial team ·

The four stages

  1. Request — the client could not reach the address at all: timeout, connection refused, DNS failure.
  2. Response — the server answered with a status that is not a usable payload: 401, 403, 429, 5xx, or a redirect to a login page.
  3. Parse — bytes arrived but do not form the expected document: HTML instead of YAML, a Base64 blob where a profile was expected, truncated content.
  4. Load — parsing succeeded but the profile is incomplete or the core rejects it: no proxies, no proxy-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 errorMinimum evidence to keepFirst action
Timeout, connection refused, HTTP 401/403/429/5xxTime, status code, whether the provider panel can issue a new linkCheck network, credentials, rate limits or service state — do not edit YAML yet
the remote profile data is invalid yamlClient version, masked error, the content type you observed locallyConfirm the body is a Clash/Mihomo profile and not HTML, Base64 or partial YAML
Missing proxies or proxy-providersTop-level key names, the format the provider says it is servingCheck whether you imported the wrong format or a profile that genuinely lacks those keys
Update reported success, proxy list emptyActive profile, provider state, proxy-group referencesCheck 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

SymptomSave this firstCheck firstNot established
Timeout, cannot connectTime, network, update method, log textLocal network, current proxy path, service stateThat the subscription is revoked
401 / 403Status code, whether a fresh link can be copied from the panelToken, permissions, access restrictionThat the provider has stopped operating
429Retry-After, time, number of attemptsThe wait window and the provider's rate-limit noteThat refreshing faster will help
200 but zero nodesContent type, body length, whether it is HTMLWhat the body actually is, and client format supportThat a 200 means a valid subscription
Nodes appear, core failsCore log, versions, config fieldsCore compatibility, fields, ports, filesThat 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.