This checklist covers failed subscription downloads, parse errors, and empty node lists in v2rayN, v2rayNG, and v2flyNG. Check the link, response, encoding, update route, protocol compatibility, and local environment in order. Update after each step and record the result to isolate the client, network, or subscription service.
First identify where the failure occurs
“Subscription failure” is not a single fault. During an update, the client must read the URL, resolve the domain, establish a connection, receive the response, decode the content, and parse the nodes. Failures in the first four stages usually show as timeouts, refused connections, or HTTP errors; failures in the last two often show a successful request but zero nodes.
Before troubleshooting, keep the original subscription group and avoid repeatedly deleting, recreating, or bulk-editing nodes. In v2rayN 7.x, open the log panel in the main window, then run “Subscription Groups” → “Update All Subscriptions” once. On Android, update the target group from the subscription group page in v2rayNG or v2flyNG and record the complete error message.
Use two results to locate the failure: whether the request received a valid response, and whether that response produced nodes. If the log stops during connection setup, prioritize the fourth check, update route, and the sixth check, local environment. If several kilobytes arrive but no nodes appear, check the second item, response type, the third, encoding, and the fifth, protocol compatibility.
Step 1: Check whether the subscription URL is complete or expired
The most common subscription problem is an incomplete copy. URLs with query parameters often contain a question mark, equals signs, and multiple values. Line wrapping in chat apps, truncated browser displays, or manual text selection can cut off the final token. A single missing character may make the server return unauthorized, empty content, or a generic error page.
In v2rayN 7.x, open “Subscription Groups” → “Subscription Group Settings”, select the target group, and verify the URL. Do not rely only on the visible beginning and end of the input field; select all, copy again, and compare it character by character with the source page. In v2rayNG and v2flyNG, open the subscription group editor and confirm there are no spaces, curly quotes, or line breaks around the URL.
Error: The remote server returned an error: (401) Unauthorized
Cause and fix: The subscription token is invalid, expired, or incomplete—obtain the full subscription URL again, replace the URL in the old group, and update it.
Error: unsupported protocol scheme
Cause and fix: The URL lacks a valid protocol prefix or begins with whitespace—make sure it starts with a valid HTTPS URL and remove whitespace from both ends.
Error: 404 Not Found
Cause and fix: The request path has changed or the URL was truncated—copy the complete URL again from the subscription management page instead of manually reconstructing the old path.
- Make sure the subscription URL is a single line with no spaces at either end.
- Make sure every query parameter after the question mark is present, especially the token after each equals sign.
- Confirm that the subscription is still active and the server has not issued a new URL.
- Replace only the URL; do not delete existing nodes first, so the old configuration remains available if the update fails.
If the link came from a QR code, inspect the actual text after scanning. A QR code may contain a single VMess or VLESS node rather than a subscription URL. Pasting a single-node link into a subscription field may produce a format error in some clients; others may report a successful update but fail to create a subscription group.
Step 2: Confirm that the server returns subscription data
A URL opening successfully does not mean the response is correct. The subscription server may return a login page, expiration notice, rate-limit page, or redirect page. These may look normal in a browser, but the client expects a list of node links or data in a supported format. Trying to parse HTML as subscription text can cause character errors or an empty node list.
You can open the subscription URL in a browser to inspect the response, but never publish the URL or paste its full token on a public page. A valid response is usually a continuous encoded string or multiple protocol links on separate lines. If the page says “Sign in”, “Plan expired”, or “Too many requests”, resolve the account issue or wait for the limit to clear first.
Example of a valid multiline subscription structure:
vmess://encoded-node-data
vless://[email protected]:443?security=tls&type=ws
A response that is clearly not subscription data:
<html>
<title>Sign in</title>
</html>| Observed result | Likely issue | Next step |
|---|---|---|
| Returns 401 or 403 | Invalid token, expired permission, or unmet access requirements | Generate a new subscription URL and replace the old one |
| Returns 404 | The subscription path changed or the link was truncated | Copy the complete URL again from the original management page |
| Returns 429 | Too many updates in a short period | Stop refreshing repeatedly and try again after 10–30 minutes |
| Returns an HTML page | Redirected to a sign-in, expiration, or block page | Follow the page instructions; do not keep changing the client core |
| Returns text but the size is 0 bytes | The server-side generation task failed or the current group is empty | Confirm on the server that the subscription contains at least one valid node |
Also check redirects. Some subscription URLs first return 301 or 302 and then redirect to a temporary download URL. If the intermediate redirect requires additional verification, the client may not obtain the final content. Use the client subscription URL provided directly by the server instead of copying the temporary redirected link from the browser address bar.
Step 3: Check the encoding and line-break format
When the server returns content but parsing still fails, focus on the encoding. Common subscriptions use Base64-encoded multiline node lists, while some services return VMess, VLESS, and other links separated by line breaks. The client must identify the outer format before parsing each protocol field. An extra HTML marker, one missing character, or malformed line breaks can cause the entire list to fail.
Do not edit subscription content in a word processor before importing it. Automatic quote replacement, inserted paragraph marks, and changed line breaks can corrupt the URIs. For offline diagnosis, save it as UTF-8 plain text and ensure each node link occupies its own line, with no numbering, bullets, or leading spaces.
Error: illegal base64 data at input byte
Cause and fix: The outer encoding was truncated, contains spaces, or uses a variant the client cannot recognize correctly—retrieve the original response again instead of manually assembling the encoded text.
Error: invalid character '<' looking for beginning of value
Cause and fix: The client is reading an HTML page as JSON or subscription data—return to Step 2 and check the response page and HTTP status.
Error: failed to parse subscription content
Cause and fix: The subscription format or one of its lines does not match a structure recognized by the client—first import a test subscription containing one known-good node to confirm that the parser itself works.
- The response starts with
<htmlor<!doctype: it is a web page, not subscription data. - After decoding, every line should start with a protocol name. Check for explanatory text on any non-empty line.
- Only one line fails to import: remove that line temporarily and test again; the problem is usually in that node’s fields.
- Every line fails: check the outer encoding, character set, and subscription formats supported by the client first.
“Zero nodes” may also mean the server returns different formats for different client types. If the management page offers v2rayN, v2rayNG, or a generic subscription option, choose the type matching the current client. Do not give a configuration format intended for other software directly to a V2Ray client.
Step 4: Switch the subscription update route
A subscription request can go through the current proxy or connect directly. If the current network cannot reach the subscription domain directly, a direct update will time out. Conversely, if the selected node is already down, forcing the update through the proxy will fail too. Do not permanently choose one mode; run a comparison test based on the current connection state.
Check existing nodes
First confirm that the client still has an old node that can be started. If it connects, keep the current configuration and do not clear the list first.
Check the core status
In the v2rayN main window, check whether the core is running and verify the local listening port in the logs. The common SOCKS inbound is 10808, but use the value shown in the current configuration.
Try a direct update first
Run “Subscription Groups” → “Update All Subscriptions”, choose the option that bypasses the proxy, and record the duration and the exact error text.
Then update through the proxy
Connect to a verified working node, then update the subscription through the proxy. If the second attempt succeeds, the problem is in the network path to the subscription domain when connecting directly.
Compare both results
If both direct and proxied updates fail, check the URL and server response. If only the proxied update fails, check the current node, core status, and the actual listening port such as 10808.
The “system proxy” switch in v2rayN and the setting for whether subscription updates use a proxy are not exactly the same. The system proxy controls how other applications send requests, while subscription updates may be initiated by the client according to its own setting. Do not judge the update route solely by whether a browser can open the page; use the connection method shown in the client log.
Step 5: Check client version, core, and protocol compatibility
A subscription being downloaded and decoded does not mean every node can be used by the current core. VMess and VLESS are different protocols, and nodes may combine TLS, Reality, WebSocket, gRPC, and other transport settings. An outdated client or mismatched core may skip nodes, fail to start after import, or report unknown configuration fields in the core log.
On desktop v2rayN, open “Settings” → “Parameter Settings” → “Core Type” and verify the selected core. For configurations using VLESS, Reality, or other Xray-related fields, use an Xray core that recognizes them, and update v2rayN and the core to stable versions from the same period. Do not replace only the main program while keeping an obviously outdated core file.
Error: unknown field
Cause and fix: The configuration contains fields unknown to the current core—update the client and its matching core, then verify the selection under v2rayN “Settings” → “Parameter Settings” → “Core Type”.
Error: failed to load config files
Cause and fix: The node was imported, but the generated core configuration failed validation—check the field error immediately following it to identify the specific protocol, transport, or security parameter.
Error: unknown transport protocol
Cause and fix: The node uses a transport type unsupported by the current version, or the subscription field is malformed—update the core first, then ask the subscription provider to verify the node template.
- v2rayN: On desktop, check the main program version first, then the active Core Type and core log.
- v2rayNG: On Android, it uses an Xray core and is suitable for checking subscriptions with fields such as VLESS and Reality.
- v2flyNG: On Android, it uses a v2fly core. Do not assume it can directly support specific Xray extension fields.
- If some nodes in the same subscription work while others fail, the node protocols or transport combinations usually differ; the entire subscription URL is not necessarily invalid.
Keep “subscription parsing” and “node connection” separate. If nodes already appear in the list, downloading and basic parsing have usually completed. Handshake failures, unresolved server addresses, and connection timeouts should then be investigated as node or route issues, not by continuing to modify the subscription URL.
Step 6: Clear local network, time, and group caches
Only check the local environment after the first five items pass. A significantly incorrect device clock can break TLS certificate validation; faulty DNS results can prevent the subscription domain from connecting; security software or a firewall may block the client core; and an old group cache may prevent updated nodes from replacing the expected entries.
Correct the system date, time, and time zone, then fully exit and restart the client. Test the current network and another working network separately. If the same subscription updates within 5 seconds on another network but consistently times out at around 30 seconds on the original network, suspect DNS, the gateway, or the network exit rather than subscription encoding.
Does the subscription update always time out?
Record when the timeout occurs, then switch between direct and proxied updates. If both modes fail after the same fixed interval, check the subscription domain’s DNS result, system time, and outbound firewall rules.
Did the update succeed but the node list remain empty?
Open the target subscription group, confirm the returned node count, and check whether filters are enabled. Temporarily disable name and protocol filters, then update once more to inspect the original list.
Can the computer update it while Android cannot?
In v2rayNG or v2flyNG, paste the same complete URL again, temporarily disable Private DNS settings that may rewrite network requests, and confirm the device date and time zone are correct.
What does it mean if switching networks fixes the issue immediately?
It likely means the subscription URL and client parser are working. On the original network, focus on DNS, gateway restrictions, and the connection path to the subscription domain; there is no need to recreate every node.
Should the subscription group be deleted immediately?
Export or keep the old configuration first. Create a test group only after confirming the URL is valid and the cache is suspect. Once the test group imports successfully, decide whether to remove the old group.
- System time: keep the difference from standard time within 1 minute, and make sure the time zone is correct.
- DNS comparison: switch networks, resolve the subscription domain again, and check whether it still returns a reachable address.
- Firewall check: allow the v2rayN main program and the active core process to make outbound connections.
- Port check: confirm that local ports such as 10808 are not occupied by another process; use the value in the log as the authority.
- Group check: disable filters and confirm that new nodes are not hidden by name, protocol, or group rules.
When creating a test group, use the same URL and update that group only once. If the test group works but the old group remains empty, the issue is concentrated in the old group’s settings or cache. If both groups produce identical results, return to checking the server response and network route instead of creating more groups.
Verify these four results after the fix
A fix is not confirmed merely because no dialog appears. Verify all four layers: the subscription request, node generation, core startup, and an actual connection. Update the target group and record the total node count; start the core with one node and check the local listening port; then make a request from an internet-enabled app and confirm a new outbound entry in the core log.
| Verification layer | Pass criteria | Where to resume if it fails |
|---|---|---|
| Subscription request | No 401, 404, 429, or timeout; the response is not empty | Steps 1, 2, or 4 |
| Node generation | The post-update node count is greater than 0, with names and protocols visible | Steps 3 or 5 |
| Core startup | The log shows the inbound port listening, with no configuration field errors | Steps 5 or 6 |
| Actual connection | The app request creates an outbound log entry, with stable results across 3 consecutive tests | Node, route, or system proxy settings |
If the subscription is restored but one node still cannot connect, stop refreshing the subscription. Test two other nodes in the same group separately. If all three fail, check the local core and network; if only one fails, the issue is usually that node’s address, port, or route.
A complete troubleshooting record should include the client name and version, core type, update time, exact error text, direct and proxied results, and returned node count. Together, these details distinguish an expired URL, a server-side error, client incompatibility, and a blocked local network—without repeatedly changing settings based only on the words “subscription failure”.