Use this checklist if v2rayN times out, reports an HTTP error, or finishes updating without adding any servers. First determine whether the request failed or the response could not be parsed, then check the response body, update route, client identification, and group filters. Change one setting at a time, and keep your original configuration and redacted logs so you don't lose working servers.
First, pinpoint where the update failed
A subscription URL provides a collection of server configurations, not a server you can connect to directly. v2rayN first requests the URL, identifies the response format, then adds the servers to the appropriate group. Whether a server connects is a separate issue: a successful subscription fetch does not guarantee that a remote server is reachable, and working servers do not mean the subscription URL is still valid.
Open the “Subscription groups” menu on the main screen and update only the group you're troubleshooting. Menu labels can vary slightly between WPF and Desktop interfaces and across versions. The steps below refer to the options that explicitly distinguish the route, such as “Update current subscription (without proxy)” and “Update current subscription (via proxy).” The system proxy toggle is not a substitute for choosing a subscription update route.
| What you see | Check first | Next step |
|---|---|---|
| Times out after a long wait | DNS, network route, proxy exit | Compare direct and proxied updates |
| HTTP 401 or 403 | Token, access restrictions, request headers | Check your account and subscription URL |
| HTTP 200, but no servers are parsed | Response body and format compatibility | Check whether the response is a web page or empty |
| Import reports success, but the list is empty | Group selection, search, and filters | Switch to the target group and clear the search |
| Servers are listed, but none connect | Server configuration or running core | Check connection and core logs |
Check the subscription URL: rule out login pages and expired tokens
Copy the “subscription URL” again from your provider's account page. Don't copy the account management page, plan details page, or a URL from a browser session after logging in. Query parameters often contain access tokens, and a single missing character can change the request. After pasting the URL into “Subscription group settings,” check for leading or trailing spaces, line breaks, or typographic quotation marks. In particular, don't manually remove anything after the question mark.
-
Back up your current configuration
Use the client's built-in backup feature. If you need to back up the configuration directory, exit v2rayN before copying the actual data directory. Don't delete all groups while you still have working servers.
-
Check the subscription URL
Go to “Subscription groups” → “Subscription group settings,” edit the target group, and paste the complete URL again from your provider's page. Make sure you're editing the group that reported the error.
-
Check your account status
Check whether the subscription has expired, its token has been reset, or your provider requires a new URL. If the token was reset, the old URL is expected to stop working; repeated retries won't help.
-
Check the response
Check the response status and body type in a trusted local environment. If you see a login form, CAPTCHA, or plan page, ask your provider for a subscription endpoint intended for client apps instead of saving the web page and trying to import it.
Opening a URL in a browser is only a reference point. The browser may send login cookies, use a different proxy, or automatically pass a web challenge—conditions v2rayN's subscription request may not share. An HTTP 200 response only means the request succeeded; it doesn't prove the body contains server configurations.
Base64 and server formats: a response with content isn't necessarily parseable
A common subscription response is a list of share links encoded in Base64, though some endpoints return plain-text links directly. Base64 is an encoding, not encryption. Even if the response decodes successfully, it might contain an expiration notice, an error message, or a configuration format the client doesn't recognize. Always inspect the decoded content.
- Outer subscription encoding: Decoding it should usually produce share links, one per line. Decode it locally only; don't send the full output to anyone.
- VMess share data: Traditional share data after
vmess://may have its own Base64 layer, separate from the outer subscription encoding. - VLESS share data:
vless://usually uses a URI structure to represent the address and parameters. Don't try to decode the entire link as Base64. - Incompatible format: YAML for another configuration system, an HTML page, or an error JSON object won't become an importable v2rayN subscription just because you rename it with a
.txtextension.
If only some servers from a response are imported, check the protocols, transport parameters, and client parsing support for the failed entries first. If none are imported, confirm that the endpoint returns the expected format before investigating encoding issues. Don't start by changing the core configuration: switching to the Xray or V2Ray core usually won't help if the client hasn't parsed the subscription text and is downloading a web page instead.
| What the body looks like | What it means | What to do |
|---|---|---|
<!DOCTYPE html> or <html | The response is a web page | Check the subscription endpoint, login requirements, and web protection |
| JSON error object | The endpoint returned an application error | Read the error message and check your account or token |
| Empty body or whitespace only | No data to parse | Ask your provider whether servers have actually been assigned to your subscription |
| Multiple lines of protocol share links | May be a supported plain-text subscription | Check protocol support and make sure each entry is complete |
| Long string of encoded text | May be outer-layer Base64 | Decode it locally and inspect the result; don't guess from its appearance |
Update route: test direct and proxied connections separately
“Update without proxy” and “Update via proxy” change the network route to the subscription server; they don't change the subscription content on that server. If the endpoint is unreachable directly, a proxy may let the request through. Conversely, the endpoint may block proxy traffic or allow access only from certain networks, in which case a direct connection may work better.
-
Try a direct update first
Select the target group, then choose the update option without a proxy from the “Subscription groups” menu. Note the time and status code of the error; don't click repeatedly.
-
Verify a working server
If you have a server that still works, select it and make sure the core is running, then try to visit a website you can access. Selecting a server doesn't prove the local proxy is working.
-
Try updating via proxy
Run the update via proxy and compare the results. If only this method works, the direct network route is a more likely cause than the subscription format.
-
Change one variable at a time
If both methods fail, keep the original URL and compare the errors. Don't change DNS, User-Agent, and server parameters at the same time, or you won't know which change mattered.
Updating via proxy still depends on a local listening port. Go to “Settings” → “Parameter settings” and check the current local inbound listener configuration. For example, if the actual listener is 127.0.0.1:10808, your test tool must use that port and a supported proxy protocol. 10808 is only an example to check against, not a fixed value for every version or setup. Don't substitute a remote server port.
Error: Connection refused
Cause and fix: The target actively refused the connection. If the log points to the local proxy port on 127.0.0.1, check that the core is running and the port matches your current settings, then retry the proxied update. If the log points to a remote address, check that remote service.
Error: No such host is known.
Cause and fix: The hostname couldn't be resolved. Check that you copied the full subscription domain and verify which DNS the current request route uses. Changing a server's SNI won't fix a subscription domain lookup failure.
Error: A task was canceled.
Cause and fix: The request may have timed out or been canceled. This message alone doesn't prove that the endpoint is invalid. Check the surrounding logs to see whether it timed out, then test both direct and proxied routes.
User-Agent and HTTP status codes: check the endpoint's requirements
User-Agent is a request header that identifies the client. Some subscription endpoints use it to select an output format or restrict access. In “Subscription groups” → “Subscription group settings,” edit the target group. If your version has a “User-Agent” field, keep the default or enter the value specified by your provider. If there's no such field, don't append an identification string to the subscription URL.
Changing the User-Agent isn't a universal fix. A browser User-Agent may cause the endpoint to return a web page, while an incorrect client identifier may make the server return an incompatible format. Change it for one group at a time, then compare the status code and body type. Restore the original value if nothing improves. If you encounter a web challenge, ask your provider for an endpoint suitable for client apps rather than trying to bypass the challenge.
Error: Response status code does not indicate success: 403 (Forbidden).
Cause and fix: The server rejected the request. Possible causes include a token issue, a restricted exit IP, or request-header requirements. First check your subscription access and URL, then verify the User-Agent against your provider's requirements. A 403 alone doesn't identify the cause.
Error: Response status code does not indicate success: 404 (Not Found).
Cause and fix: The requested resource wasn't found, or the endpoint is deliberately hiding an invalid resource. Get the subscription URL again from your account page; don't guess the path or edit its parameters.
Error: Response status code does not indicate success: 429 (Too Many Requests).
Cause and fix: The request hit a rate limit. Stop clicking repeatedly and pause overly frequent automatic updates. Wait as directed by the Retry-After header or your provider before trying again.
The messages above are common HTTP client error formats; capitalization and extra text may vary by version. Recording the numeric status code is more useful than noting only “update failed.” For a 5xx response, check the endpoint or upstream service. Repeatedly changing local protocols won't fix a server-side error.
Groups and filters: why the list may still be empty after a successful update
Even when the request and parsing both succeed, an empty list may simply mean you're looking in the wrong place. Switch to the group you just updated, clear the search box, and check for a server-name filter. Then go to “Subscription group settings” and review the options available in your version, such as “Enable updates,” keyword filters, regex filters, and deduplication. Note the original values, then temporarily remove the filters while troubleshooting.
- Check which group you updated: Groups with the same name are easy to mix up. Compare both the group notes and subscription URL to avoid editing one group and updating another.
- Check name filters: A regex that's too broad or contains an unintended space may filter out every server. Clear the filter first, then check how many entries were imported.
- Distinguish deduplication from failure: Deduplication can make the number of new entries lower than the number in the response without indicating a download failure. Compare the update log with the total number of entries in the group.
- Check whether updates are enabled: If updates are disabled for a group, it may be skipped when updating all subscriptions. Make sure the group is enabled for updates.
Common questions and final checks
Why can my browser download the subscription when v2rayN can't?
First check whether both use the same network route, then confirm that the browser actually downloaded server text. The browser may send login cookies. If the response is a login or verification page, switch to a subscription URL intended for client apps. Then check the User-Agent required by your provider.
Can I update via proxy if all my servers are gone?
Updating via proxy requires a working proxy connection. Restore a known-good configuration from a local backup or use another legitimate connection method from your provider. If you have no working proxy, test a direct connection first or ask your provider for an accessible subscription endpoint. Turning on the system proxy alone can't establish a connection.
If v2rayNG imports the subscription, does that mean the desktop client is broken?
Not necessarily. First confirm that both clients received the same response—not just that they used the same URL. Their network routes, User-Agents, and endpoint routing may differ. If the responses match, compare support for the specific protocols and transport parameters. v2rayNG uses the Xray core, while v2flyNG uses the v2fly core, but subscription parsing compatibility still depends on the client version.
The update added servers, but every connection test fails. Should I keep changing the subscription?
Stop changing the subscription for now. Check that the core starts, verify the system time, server address, port, and TLS settings, and read the core logs for the connection attempt. Subscription updates and server connections are separate stages. Once the list is populated, focus on the specific server and network route.
A useful recheck confirms all three: the request succeeded, the response was recognizable, and the group contains servers. Don't rely only on the update finishing. If you need to report the issue, include your actual v2rayN version, interface, operating system, update method, HTTP status code, and redacted error text. Don't share server credentials, subscription tokens, or the full response body with your logs.
- When retesting the same group, keep the URL and filters unchanged and change only one factor at a time.
- After a successful update, check the servers in the target group, then test the selected server's connection separately.
- Once the issue is resolved, restore a sensible automatic update schedule and keep a recoverable local backup.