This guide is for anyone who needs to inspect subscription content, migrate a single node, or troubleshoot an import failure. By the end, you’ll be able to distinguish encoding containers, share links, and core configuration, then convert between them through explicit field mappings.
First, separate encoding, nodes, and runtime configuration
“V2Ray subscription” is not a single, strictly standardized file format. In practice, it may refer to a URL that returns multiple share links, a decoded node list, or JSON configuration that can be read directly by the V2Fly or Xray core. All three may contain server details, but their purpose and level of detail differ.
Base64 is an encoding method, not a protocol. It converts text into transport-friendly characters; it does not validate servers, fill in transport parameters, or create routing rules. A typical subscription response contains newline-separated vmess://, vless://, or trojan:// links, with the entire payload Base64-encoded once at the outer layer.
A share link describes one outbound node. It usually contains the server address, port, user ID, transport, TLS settings, and a remark. Native JSON targets core runtime configuration; in addition to outbounds, it may include inbound listeners, DNS, logging, routing rules, and policies. Extracting a share link from JSON can therefore preserve only one outbound, while converting it back cannot recreate the original rule set.
Base64 subscription
RecommendedBest for publishing multiple nodes centrally, with clients refreshing them periodically from the subscription URL. Decoding usually produces plain text with one share link per line.
Best for: routine subscription updates and multi-node groups
Single share link
Easy to copy one node and import it on another device; the fields focus on that node’s outbound connection parameters.
Best for: migrating one node and checking parameters individually
Native JSON
Expresses the core configuration tree directly and can contain multiple inbounds, outbounds, DNS settings, and routing rules. It offers the most complete structure.
Best for: fine-grained routing and manually maintained core configuration
Takeaway: identify the outer layer before parsing the inner content
When you see a long string, do not decode it repeatedly. First determine whether the response is JSON, a plain-text link list, or Base64 text. After each conversion, verify that a valid protocol prefix appears in the result.
What is inside a Base64 subscription?
A typical subscription service returns plain text. After receiving the response, the client trims surrounding whitespace, performs one Base64 decode, and splits the result on \n or \r\n. Empty lines should be ignored; each non-empty line is then passed to the parser for its protocol prefix. If the decoded result begins with a left brace, it may be JSON and should not be split as a link list.
Standard Base64 uses uppercase and lowercase letters, digits, plus signs, and slashes, with optional equals signs for padding at the end. The URL-safe variant replaces plus and slash with hyphen and underscore. Some subscriptions omit trailing padding; parsers may restore it based on the length, but must not alter the middle characters. A UTF-8 byte-order mark, messages around the response, or an HTML error page can also cause decoding to fail.
Outer subscription response
↓ decode Base64 once
vmess://encoded node description
vless://[email protected]:443?encryption=none&security=tls&type=ws#Example node
trojan://[email protected]:443?security=tls&type=tcp#Backup node
↓ identify the protocol line by line
Node 1, Node 2, Node 3To determine whether content is really a subscription, do not rely only on whether its characters fit the Base64 alphabet. Short English text, digit strings, and even ordinary text may happen to match. A safer check is whether the decoded UTF-8 text contains supported protocol prefixes or valid-looking JSON. Also check the server response status: enter the parsing flow only for a response such as HTTP 200; handle 301 or 302 redirects according to client policy, while 401 and 403 usually indicate changed credentials or access conditions.
Common response patterns
- Plain-text list: The first line directly begins with
vmess://,vless://, ortrojan://; no outer decode is needed. - Encoded list: The response body is one continuous string, and decoding it once reveals multiple protocol links.
- JSON response: The top level may be an object or an array. Read it according to the provider’s specification instead of applying generic line-splitting rules.
- Error page: The content begins with
<htmlor a readable error message. Stop the conversion and check the subscription URL.
VMess and VLESS share-link field differences
A common vmess:// format places a complete node JSON object, encoded as a whole, after the protocol prefix. The decoded object commonly includes the version, remark, server address, port, user ID, transport, camouflage type, path, TLS, and SNI. Field names are often abbreviated in legacy implementations: add means address, port means port, and id means user ID.
vless:// is closer to a standard URL: the user ID is in the username position, the host and port are in the authority section, transport and security settings are in the query string, and the remark follows the hash. Always URL-decode percent escapes before parsing, and keep query parameters separate from the fragment. Port 443 is commonly used for TLS connections, while port 80 is common for HTTP or WebSocket endpoints without TLS; the port alone cannot prove whether a security layer is enabled.
| Connection information | Common VMess fields | VLESS URL position | Conversion notes |
|---|---|---|---|
| Server address | add |
Host section | Domain names and IPv6 addresses use different syntax; preserve the brackets required for IPv6. |
| Port | port |
Port after the host | Convert it to an integer from 1 to 65535. |
| User ID | id |
Username section | Copy only the existing value; do not derive it from the remark or server address. |
| Transport | net |
type parameter |
WebSocket, TCP, and gRPC use different additional fields. |
| Path or service name | path |
path or serviceName |
Slashes, spaces, and special characters must be encoded correctly. |
| Server name | sni |
sni parameter |
Do not assume it is the same as the connection address. |
| Remark | ps |
Fragment after the hash | Affects only the display name; it is not used to establish the connection. |
In VMess links, different generators may write Boolean values as strings and ports as numbers or strings. A conversion tool should normalize types before producing the target format. VLESS links also require handling duplicate query parameters, parameter casing, and percent encoding. Unknown parameters are best preserved in extension fields rather than silently discarded.
Takeaway: matching protocol names do not guarantee equivalent parameters
At minimum, verify the address, port, user ID, transport, security layer, SNI, and path. Copying only the first three often produces a node that imports successfully but cannot connect.
Why native JSON cannot be used directly as a subscription
Core JSON is a complete runtime configuration. A typical desktop configuration declares a local inbound, such as a listener on loopback at port 10808, and then defines one or more outbounds. Routing selects an outbound based on domains, IPs, or inbound tags, while DNS settings determine how names are resolved. A share link cannot express this relationship in full, so clients generally apply their own default inbound and routing templates.
The structure below shows field hierarchy only; its explanatory text is not a directly usable connection configuration. It shows that an outbound node must be nested under outbounds in native JSON, while the local proxy port belongs under inbounds. The two must not be confused.
{
"inbounds": [
{
"listen": "127.0.0.1",
"port": 10808,
"protocol": "socks"
}
],
"outbounds": [
{
"tag": "proxy",
"protocol": "vmess",
"settings": {
"vnext": [
{
"address": "edge.example",
"port": 443,
"users": [
{
"id": "User ID assigned by the service provider",
"security": "auto"
}
]
}
]
},
"streamSettings": {
"network": "ws",
"security": "tls",
"wsSettings": {
"path": "/gateway"
}
}
}
]
}To generate a VMess share link from native JSON, first select the target outbound, then read the server and user information from settings.vnext, and finally map streamSettings to the transport fields. If an outbound contains multiple servers or users, it may need to be expanded into multiple links. When generating JSON in the reverse direction, the client must also add local inbounds, logging, and default routing values.
Content commonly lost during conversion
- Routing rules and their priority based on domains, IPs, ports, or processes.
- Load balancing, failover, and tag references among multiple outbounds.
- The listener address and port for local SOCKS, HTTP, or transparent-proxy inbounds.
- DNS servers, domain-matching rules, cache policies, and query paths.
- Log levels, statistics policies, and extensions valid only for specific core versions.
Steps for converting a subscription into share links
Reliable conversion should use a layered workflow rather than repeatedly trying to decode the text. Keep an untouched copy of the original response, record its content type and character encoding, and then identify the outer layer. After parsing, build a normalized node model and have separate output generators produce VMess, VLESS, or core JSON. This makes it easier to identify whether an error occurred during retrieval, decoding, field parsing, or output.
Check the response
Confirm that the request returns HTTP 200 and that the content is not a login or error page. Record whether the response contains line breaks, a JSON opening character, or a recognizable protocol prefix.
Decode the outer layer
Perform one Base64 decode only when the content matches the characteristics of an encoded subscription. Support both the standard and URL-safe alphabets, and read the result as UTF-8.
Split the nodes
Split on CRLF or LF and remove blank lines. Dispatch each line to the parser indicated by
vmess://,vless://, ortrojan://.Normalize fields
Convert the port to an integer, standardize the transport name, store the address, user ID, TLS, SNI, path, and remark separately, and preserve unknown fields on their own.
Import and validate
In v2rayN, open “Settings” → “Parameter Settings” → “Core Type” and confirm that the selected core supports the target protocol. Import the result into a new group and inspect the core log.
Validation should not stop at “Import successful.” That message means only that the client accepted the syntax. Also check the server, port, and transport settings in the node details, then inspect the log after startup for DNS failures, TLS name mismatches, path errors, or port conflicts. If the local port is 10808, make sure no other process is using the same listener.
Checks suitable for automation
- Whether the subscription response size is reasonable; stop parsing immediately if it is empty.
- Whether the decoded result is valid UTF-8 and whether malformed bytes come from an unexpected character set.
- Whether every node’s port is between 1 and 65535.
- Whether SNI or the corresponding server name is preserved when TLS is enabled.
- Whether the WebSocket path begins with a slash and whether query parameters have been encoded more than once.
- Whether the node remark has been URL-decoded without allowing it to overwrite connection fields.
Importing into v2rayN, v2rayNG, and v2flyNG
v2rayN is well suited to managing subscription groups on desktop systems. After adding a subscription URL, run an update to fetch and parse the node list. If you have only a single share link, use the clipboard import option. Menu labels may vary slightly between versions, but the sequence remains the same: create a subscription group, update it, then select a node and enable the system proxy.
v2rayNG uses the Xray core, while v2flyNG uses the V2Fly core. Both can handle common VMess subscriptions and share links, but support for specific protocol extensions depends on the core. If a link parses successfully but startup reports an unknown transport or security type, check the core capabilities required by the link instead of continuing to alter the Base64 content.
No nodes after pasting the subscription URL?
First check the HTTP status in the client log rather than relying on the browser. If it returns 200, confirm that the decoded result contains protocol prefixes arranged one per line. If the response is a JSON object, use the corresponding import method.
Why is the result still garbled after one decode?
Check whether the text uses URL-safe Base64 and restore the trailing equals signs. If it still fails, see whether the response contains messages, a UTF-8 byte-order mark, or HTML error content.
The node imports successfully but cannot connect?
Check the port, transport, TLS, SNI, and path one by one, then inspect the core log. A missing slash in a WebSocket path or omitted SNI can cause the handshake to fail within seconds.
Will a subscription update overwrite manual remarks?
Most clients rebuild the group from the latest subscription content, so manually edited names may be replaced. Copy nodes that must be kept long term into a separate group and record their original subscription.
Can native JSON be imported directly into the subscription field?
Usually not. The subscription field expects a URL or node list. Use the client’s custom-configuration entry point for core JSON, then check inbound ports, routing, and DNS settings separately.
When troubleshooting core selection in v2rayN, open “Settings” → “Parameter Settings” → “Core Type” to view the current setting. If the list does not change after an update, first confirm that the correct group was refreshed, then check the log timestamp. Before importing on a mobile device, verify that the clipboard content is complete. When a long link is truncated by a chat app, the ending remark may still appear present even though query parameters in the middle are missing.
Four checks after importing
- Field check: The server, port, transport, and other values in the node details match the original content.
- Core check: The selected core supports the protocol and transport extensions declared by the link.
- Log check: After startup, there are no port conflicts, DNS resolution errors, or TLS handshake failures.
- Group check: Keep manual nodes and subscription nodes in separate groups so the next update does not overwrite settings that must be retained.
Conversion boundaries and maintenance advice
The goal of subscription conversion is to preserve connection parameters, not to produce a link that merely looks similar. When a tool encounters an unknown field, preserving the original data and clearly reporting it is more reliable than deleting it and continuing. This is especially important for transport extensions and security settings: a link may remain syntactically valid while behaving differently after those fields are lost.
The subscription URL usually serves as the update entry point. After exporting a node retrieved at one moment as a static share link, it will not automatically receive later changes to the server, port, or user information. For long-term use, keep the original subscription group; static links are better suited to temporary migration or parameter analysis.
Native JSON is better suited to preserving verified routing and inbound settings. Before editing, record the current local listener port, system proxy state, core type, and configuration-file source. If something goes wrong, restore these basics first and then inspect node fields to avoid mistaking a system-proxy issue for a subscription-format problem.
| Goal | Recommended input | Recommended output | Must verify |
|---|---|---|---|
| Update multiple nodes regularly | Subscription URL | Client subscription group | Update status, group membership, and protocol support |
| Migrate one node | Single share link | Create a new node | TLS, SNI, path, and remark |
| Maintain fine-grained routing | Native JSON | Dedicated core configuration | Inbound port, DNS, and routing tags |
| Analyze subscription content | Original response | Read-only decoded copy | Decode only one layer and avoid exposing connection information |
The safest workflow keeps three separate artifacts: the untouched subscription response, the normalized node fields, and the final import file. With these separated, any connection problem can be traced to a specific conversion stage. For everyday use, let the client manage subscriptions directly; manually handle encoding and JSON mapping only when migrating, debugging, or building custom routing.