Why the same subscription URL works in one client and fails in another — the three formats, the metadata header, and the conversion traps that silently break nodes.
This is the technical layer under most "import failed" and "invalid yaml" errors. If your client rejects a subscription that works in a browser, the answer is almost always in this document.
A subscription URL returns one of these. They are not interchangeable, and most providers serve a different one per path or query parameter.
The body is a base64-encoded block of one-per-line share links:
dm1lc3M6Ly9leUoySWpvaU1UQXd... (base64 of the block below)
Decoded:
vmess://eyJ2IjoiMiIsInBzIjoi...
vless://uuid@host:443?type=ws&security=tls#name
trojan://password@host:443?sni=example.com#name
ss://base64method:password@host:port#name
Consumed by: v2rayN, v2rayNG, and most Xray-family clients.
Two traps specific to this format:
vmess://is not a standard URI. The part after://is base64-encoded JSON (v2rayN's own convention). A strict URI parser rejects it.- The whole block is base64 with possible line breaks. Clients that strip newlines first succeed; clients that don't fail with a decode error.
proxies:
- name: "node-1"
type: vmess
server: example.com
port: 443
uuid: xxxx
alterId: 0
cipher: auto
tls: true
proxy-groups:
- name: "PROXY"
type: select
proxies: ["node-1"]
rules:
- DOMAIN-SUFFIX,example.com,PROXY
- MATCH,PROXYConsumed by: Clash Verge Rev, FlClash, Stash (compatible), and anything Mihomo-based.
A Clash config is an entire configuration, not a node list. This is the key asymmetry: a base64 node list cannot become a Clash config without a converter adding proxy-groups and rules.
{
"outbounds": [
{ "type": "vmess", "tag": "node-1", "server": "example.com", "server_port": 443, "uuid": "xxxx" }
],
"route": { "rules": [], "final": "node-1" }
}Consumed by: sing-box, Hiddify, Karing.
sing-box has moved fields between versions — most notably around tunnel-per-resolver and rule-set handling. A config written for a newer core fails on an older one with an unknown field error, and vice versa.
Most clients read subscription quota from a response header, not the body:
subscription-userinfo: upload=123456789; download=987654321; total=107374182400; expire=1767225600
| Field | Meaning | Unit |
|---|---|---|
upload |
bytes sent | bytes |
download |
bytes received | bytes |
total |
quota | bytes |
expire |
expiry | Unix timestamp, seconds |
Practical notes:
expire=0usually means no expiry, but some panels use0to mean "unknown" — they're not distinguishable from the header alone.- Clients display this in GB (÷ 1024³). A provider advertising "100GB" that shows 93.1GB in the client is using decimal GB in marketing and binary GB in the header. Both are common.
- If the header is missing, clients show "no quota info" and fall back to whatever you configure manually. Absence of the header does not mean the subscription is broken.
People run subscriptions through a converter (subconverter or similar) to switch formats. This is where silent data loss happens.
What a converter typically does:
| Action | Consequence |
|---|---|
| Renames nodes | Your rules and proxy-group references point at names that no longer exist |
| Drops unsupported fields | alterId, flow, packet-encoding, plugin options disappear silently |
| Reorders outbounds | The "first node" or default selection changes |
| Rewrites the transport | ws path/host may be normalized; non-standard values get dropped |
| Re-encodes base64 | Padding and line-break differences break clients with strict decoders |
What it cannot do: infer information the source format didn't carry. If the base64 node list has no rules, the converter invents a default ruleset — which is why converted configs often route traffic differently from the original.
When a subscription works in one client and fails in another:
- Fetch the URL with
curl -iand look at the first bytes. Is itproxies:,{, a base64 string, or<? If<, you have an HTML page (login wall, 404, or a challenge) with a 200 status — that is the fault, and nothing downstream will fix it. - Check
Content-Encoding. A gzip body handed to a client expecting plain text produces a parse error that looks like a format problem. - Check
Content-Type.text/htmlwhere you expectedtext/yamlorapplication/jsonconfirms step 1. - Compare byte size against expectation. A subscription that returns 200 bytes is an error page, not a config.
- Decode the base64 manually. If it doesn't decode, the client isn't the problem.
- Only then consider the client's parser.
Subscription URLs contain a token that grants access to your account's traffic. Before pasting into an issue:
- Strip the token from the URL path/query
- Remove
uuid,password, and node server addresses - Replace subscription hostnames
- Remove any
subscription-userinfovalues that map to your account
A leaked subscription token lets someone else consume your quota, and in many panels it's the only credential — there is no second factor.
Machine-readable version of this reference (field mapping and the full error table, no JavaScript): https://overnice2025.github.io/
If this explained an import failure you'd been debugging, star the repo.
- Error code reference — the exact errors these format mismatches produce
- Proxy client comparison matrix — which client consumes which format
- Subscription basics (ZH) — full walkthrough from purchase to import to expiry
- Subscription conversion safety (ZH)
If a converter behavior listed here has changed, open an issue with the converter version and a minimal input/output pair.
MIT — see LICENSE.