One-minute symptom routing
| Symptom | Most likely layer | Do this first |
|---|---|---|
| An error appears immediately after adding the URL | Address, authorisation or network fetch | Confirm the URL is complete; keep the HTTP status or error text |
| No nodes after an update | Fetch, content or parse needs checking | Keep the message and check what the source actually returned |
| The profile name exists, but the content looks old | The selected profile needs checking | Return to the profile list and confirm which one is in use |
| Nodes appear, connecting still errors | Moved on to connection or compatibility | Disconnect first, then record the earliest error |
| Nodes appear but all time out | Node or current network unreachable | Switch to a reachability check; stop re-importing |
Step 1: is the copied value a subscription or a share link
Hiddify's URL scheme documentation states that an import target can be a Clash link, a sing-box link, a v2ray subscription or a single proxy share link. A site homepage, a login page or a plan purchase page is not a configuration.
- Re-copy from the source's “copy subscription”, “import to Hiddify” or an explicit configuration entry.
- Check whether a chat app truncated the parameters after the question mark, or carried a full stop, space or line break along with the copy.
- If the link has already appeared in a public screenshot or group chat, rotate the token at the source before continuing.
- Do not send the full link to a stranger to “test it”; record the domain, the HTTP status and a masked error only.
Step 2: no content, or the wrong content
A remote update can fail at address access, source authorisation, response download or content parsing. These statuses are clues, not conclusions:
| Response | What it suggests | What it does not prove |
|---|---|---|
| 401 / 403 | Authorisation, token or access rule | That the source has stopped operating |
| 404 | Incomplete path, or a changed entry point | That the subscription was deleted |
| 429 | Too many requests | That refreshing again will help |
| 5xx or timeout | Source or network, not yet separable | Which side is responsible |
| 200 with an HTML body | Login page, captcha or error page | That a 200 means a configuration |
| 200 with an empty body | Nothing to parse | That a client setting will fix it |
Do not use an online converter to inspect the body. If you must check it, do so on a device you control and mask the credential.
Step 3: an explicit parse error is a different branch
If the message contains [SingboxParser] unmarshal error, an outbounds[n] position and unknown field "tunnel-per-resolver", the content was retrieved and parsing began. That is not “the list is empty after fetching” — it is a field-level incompatibility between the content and this build.
| Earliest evidence | Handle first |
|---|---|
| HTTP 401/403, timeout or TLS error | Fetch and authorisation |
| Content retrieved, then a specific unknown field | Keep a masked error and the client version; check the provider's output format |
| No parse error, profile saved, no nodes | Continue with profile selection, filtering and startup checks |
Hiddify issue #2295 and issue #2203 document such cases on Android and Windows respectively. Neither provides a fix conclusion that generalises to every version. Do not delete fields from your only copy of the original profile; record the field, the array position, the source entry and the version, then ask the provider to check their output.
Step 4: is the new profile the active one
- Return to the profile list and confirm the newly updated entry is selected.
- Confirm it is the active configuration, not merely stored.
- If the node list still shows old names, the new configuration has not been applied.
- Keep a previously working profile as a control. It separates “this content is unusable” from “this client cannot load anything right now”.
Step 5: fetch, parse and start are three events
A successful download only proves bytes arrived. Parsing proves the structure is understood. Starting proves the core accepted the configuration and opened its listeners. Hiddify logs all three, and the first error in the log identifies the stage. Reading only the last few lines usually shows the last symptom rather than the first cause.
Safe recovery order
- Disconnect. If the system VPN indicator persists, check for another VPN or a leftover configuration.
- Switch back to the last profile that produced nodes.
- Keep the error time, app version, core version and a masked log.
- Remove the new profile only after confirming it cannot load.
- Do not clear all application data at once — that removes your control profile and your evidence together.
What to record
- Where the link was copied from, and whether it is a subscription or a share link.
- HTTP status or the exact error text, with the URL masked to domain and path shape.
- Whether the log shows a parse error, and if so the exact field name.
- Which profile is active, and whether an older profile still works.
- App version, OS, and core version if displayed.
- Whether the same subscription behaves differently in another compatible client.
Never publish the full subscription URL, a QR code, a UUID, a password or a token. If one leaked, rotate it at the source rather than deleting a message.