FAQ / Client Reference

V2Ray Troubleshooting

Check each stage of the problem, from subscription import and traffic routing to server connections.

Desktop
v2rayN
Android
v2rayNG / v2flyNG
01 / Concepts

Getting Started

Distinguish what the client displays, what the core does, and what requests apps actually send.

What are the differences between a client, core, and protocol?

The client manages configurations, lets you select profiles, and displays logs. The core listens on local ports, handles routing, and establishes connections. A protocol defines how the two ends exchange data. For example, v2rayN is a desktop client, Xray is a core, and VLESS is a protocol. To check whether a configuration will work, verify not only its protocol but also that the client can import its format and the current core supports its transport and security settings.

What’s the difference between a subscription link and a single share link?

A subscription link points to a list of profiles that can be updated, and is usually added as a subscription group. A single share link describes one connection profile and should be imported through the share-link or clipboard option. Whether a URL starts with HTTPS doesn’t tell you what format it returns. Some URLs open a login page or subscription management page rather than the subscription URL the client needs. Check the provider’s instructions, and don’t post the full link in a public forum.

Does a successful import mean the server is ready to use?

A successful import only means the client recognized and saved the profile. To use it, select the profile, start the core, and route traffic from a test app through the client. Then test a page you’re allowed to access that normally loads reliably, and check the log entry for that request. A profile appearing in the list, the core starting successfully, and an app request succeeding are three separate checkpoints. Treating them as one status can make import problems easy to confuse with connection issues.

What’s the difference between system proxy and TUN mode?

A system proxy provides a local proxy address to apps that follow the system proxy settings. Apps with their own network settings may ignore it. TUN routes traffic matching its rules through a virtual network interface; coverage depends on routing, exclusion rules, and system permissions, so it doesn’t guarantee that every app follows the same path. For browser testing, start with the system proxy. Configure TUN according to your operating system and client documentation only if you need to cover other apps.

02 / Setup

Setup

Check the installer, import method, and system permissions before assuming the server configuration is wrong.

v2rayN or v2rayNG subscription import failed: what should I check first?

First, determine whether you can’t add the URL at all or whether profiles don’t appear after adding it and updating. On desktop, save the URL in v2rayN’s subscription groups. On Android, add it in v2rayNG’s subscription settings, then run an update. Check the copied URL for line breaks, spaces, or missing query parameters. If you see a format error, check which clients the provider supports: a single share link isn’t a subscription URL, and a configuration file for another client won’t work just by changing its file extension.

Android package: arm64 or universal?

If your device supports arm64-v8a, choose the arm64 package. If you’re unsure which architecture your system supports, check your device specifications or try the universal package. A universal package includes multiple architectures bundled by the publisher and is usually larger; it doesn’t support every Android version. If Android says the app can’t be installed, also check the minimum OS version, available storage, and whether its signature conflicts with an installed version. Architecture isn’t the only possible cause.

How do I fix a permission error when enabling TUN?

Check the log to see whether virtual interface creation failed, a route change was denied, or system authorization is still pending. On desktop, follow the client’s instructions to grant elevated privileges or authorize its service. On managed devices, ask your administrator whether virtual interfaces are allowed. On Android, approve the system VPN connection request the first time you start it, and check whether another app is already using the VPN connection. Restart the mode after granting permission, then check whether the same error appears in the log.

Desktop app won’t start after downloading: how do I troubleshoot it?

First, make sure the download matches your operating system and processor architecture. Extract archives completely to a writable folder before running them; install packaged apps using your platform’s normal installation process. If no window appears, check whether the system reports a missing runtime or a device policy restriction. If the window opens but the core fails to start, check the client log for path, permission, or port errors. Identify which stage failed before troubleshooting; don’t start by clearing the configuration folder or overwriting existing files.

03 / Usage

Advanced

Keep essential settings before updating subscriptions; change only one setting at a time when comparing routes or servers.

How can I keep manually added profiles when updating a subscription?

Keep manually added profiles in a separate group, not one managed by subscription updates. Behavior varies by client and version, and an update may rebuild the group from the list returned by the server. Notes or settings changed directly on subscription profiles may not be retained. Before switching subscription sources, use the client’s backup or export feature to save any configurations you need. Exported files may contain authentication details; store them securely and don’t send them with logs.

Should I use automatic routing or global proxy?

For everyday use, start by checking the automatic routing rules and default outbound, then confirm that common apps are routed as expected. If only one type of request fails, briefly switch to global rules using the same connection method for comparison, then restore the original setting. Global rules determine which outbound handles traffic that has already reached the core; they won’t automatically route apps that aren’t connected to the client. If neither mode produces requests in the log, check the system proxy, app-specific proxy, or TUN setup.

Why is download speed slow even when server latency is low?

Latency measures the time for a probe or small request, while download speed reflects sustained transfer capacity. They aren’t interchangeable. Tests may also measure different things, such as connecting to a port, completing a protocol handshake, or making a full request. For a fair comparison, use the same device, network, and test target; repeat measurements at similar times and note packet loss, disconnections, or major speed fluctuations. If only one site is slow, compare with another target rather than judging the entire connection from a single result.

How can I switch servers without counting an old connection in the test?

First, confirm that the client’s selected profile has actually changed. Browsers, download managers, and messaging apps may reuse existing connections, and whether old connections are closed depends on how the client switches profiles. Make a new request, and if needed, close and reopen the test app. Then check the core log by timestamp to see which outbound handled it. When comparing two connections, keep routing rules, connection method, and test target the same; change only the server to isolate the difference.

04 / Diagnostics

Troubleshooting

Match a repeatable request to its log entries to find out whether the failure is in local traffic routing, connection setup, or subscription retrieval.

A server shows a timeout or a negative value. How can I narrow down the issue?

First, confirm that your local network works, then test a profile that previously worked using the same method. If only one server fails, check its address, port, and transport settings against the current subscription. If several fail at once, check whether the core started, whether the network changed, and whether the test target is reachable. Logs can help distinguish DNS resolution failures, connection failures, and handshake failures. A timeout or negative value only means that this probe didn’t return a valid result; it doesn’t prove the server is down.

The client says connected, so why can’t I access the internet?

First, disconnect the client and confirm the device’s basic network connection works. Reconnect, then use the same browser to visit a page that normally loads. If the browser reports an error and there’s no new request in the core log, check how traffic reaches the client. If a request appears, check the matched route and outbound, and look for DNS or handshake errors. If only a few domains fail, don’t reset the network, change routing, and switch servers all at once. Test each possibility against the logs to pinpoint the issue.

v2rayN system proxy is enabled, so why isn’t an app using it?

In your system network settings, check the proxy address and port, and make sure they match the local HTTP or mixed port currently provided by v2rayN. Then close and reopen the test app, make a request, and check the log. If one app that follows system settings works but another has no corresponding log entry, check whether the latter has its own proxy option or exception rules. If all apps fail, check whether the local listener is running and whether another program is using the port.

My subscription used to work. Why is it failing to update now?

First, identify whether the error is a request timeout, access denied, or a parsing failure after a response arrives. For a timeout, check whether the subscription URL is reachable over your current network. If you get a login page, error page, or access-denied message, ask the provider whether the URL changed or the subscription expired. For a parsing error, check whether the response format changed. Don’t delete the existing group before an update succeeds. Note the error type and time; when sharing diagnostics, redact the full subscription URL and authentication details.

Download V2Ray Client