V2Ray Troubleshooting Guide

1. Build a Reproducible Diagnostic Baseline

Describe the symptoms before guessing the cause

Effective troubleshooting starts with a reproducible path. Record the current client, selected node, system proxy mode, routing mode, time of occurrence, and failing application. Then distinguish between “no websites open,” “only a specific domain fails,” “the browser works but other apps fail,” and “the connection works but speeds have dropped noticeably.” A node name does not prove that a node works, and the latency shown in a list cannot replace a complete connection test. Keep a previously working node or configuration as a reference whenever possible. If the old and new configurations behave differently on the same network, you can quickly narrow the issue to node parameters or routing rules.

Next, run a minimal test: close other proxy clients, browser proxy extensions, packet-capture tools, and temporary network accelerators, leaving only one V2Ray client running. Pause custom routing rules and switch to the client’s basic proxy mode. Select one node and keep it unchanged. On desktop, also confirm that the system time, time zone, and date are correct because TLS certificate validation depends on system time. Mobile networks and Wi-Fi have different egress conditions, so record which network is active during each test. Otherwise, switching networks can lead to incorrect conclusions about the original configuration.

Locate the failure by layer

A request generally passes through the application, system proxy or virtual network interface, local inbound, routing and DNS, remote node, and destination server. If the browser generates no request in the client log, check the application and system proxy first. If the log shows a node connection timeout, focus on the path from the local network to the node. If the node handshake succeeds but the destination domain cannot be resolved, investigate DNS. If only one group of domains uses the wrong egress, check routing rule order. This layered approach is more effective than repeatedly reinstalling the client and prevents separate issues from being mixed together.

Save logs and evidence of local listening

Logs should cover the complete sequence: start the client, select a node, make one failed request, and stop the test. Do not capture only the final line, because the real cause often appears earlier during configuration loading or inbound listening. In v2rayN, check the main-window log area and core logs. In v2rayNG and v2flyNG, use the log page to observe connections, routing, and errors. Before sharing logs, remove subscription URLs, node credentials, user identifiers, and full server addresses. Keep only the error types, event order, and necessary parameters.

On desktop, verify that the local proxy port is listening. The commands below check only a local port; they do not verify the remote node. Replace the port number with the SOCKS or HTTP port actually shown in the client settings.

netstat -ano | findstr LISTENING
curl --proxy http://127.0.0.1:10809 https://example.com/

If the port is not listening, the problem is still in client startup, a port conflict, or core loading. If a command using an explicit proxy works but the browser does not, the issue is usually in the system proxy or application proxy layer. If the explicit proxy also fails, check the node and DNS. By the end of this round, you should be able to write a brief conclusion such as: “The local HTTP port is listening, browser requests appear in the log, but the connection to the node address times out.” That conclusion is the starting point for further investigation—not the vague statement “V2Ray does not work.”

2. No Internet Access After Starting the Proxy

Separate a local traffic break from a proxy-path failure

“No internet access after connecting” usually describes one of two situations. In the first, the system proxy points to the client, but the client’s local inbound is not listening properly, so every application that follows the system proxy fails immediately. In the second, the local inbound works and traffic reaches the core, but the remote node, routing, or DNS does not complete the request. Check the client log first: if visiting a webpage adds no new entry, traffic has not reached the client. If the log shows the destination domain and an outbound, the system proxy has at least delivered the request to the local core.

First disable the system proxy and exit the client, then confirm that the direct connection itself works. If the direct connection cannot reach common sites, fix the Wi-Fi, network adapter, gateway, or local DNS first instead of changing the node. Once direct access works, start the client without enabling the system proxy and confirm that the core starts without errors. Finally, enable the system proxy and visit a fixed test page. This startup order shows whether the failure begins in the original network, core startup, or proxy takeover.

Check ports, modes, and process ownership

v2rayN’s HTTP, SOCKS, and LAN listening settings are separate. The system proxy must point to the HTTP port that is currently listening; do not copy a port from another device or an old configuration. If another program occupies the port, the core may fail to start, or it may switch ports automatically and become inconsistent with the system proxy. Look for messages such as address already in use, bind failed, or listen failed. After finding a conflict, close the program using the port or choose an unused port in the client, then configure the system proxy again.

The fact that a browser opens webpages while a command-line tool does not does not necessarily indicate a node problem. Many command-line programs do not automatically read the desktop system proxy and require explicit proxy arguments or environment variables. Conversely, some applications keep their own manual proxy address and continue connecting to an old port even after the system proxy is disabled. Check the application’s network settings and distinguish “follow system,” “manual HTTP,” “manual SOCKS,” and “direct.” Results are comparable only when the same proxy entry point is used.

Return to the simplest routing configuration

Complex split-routing rules may send DNS, the node domain, or destination requests to the wrong outbound. Temporarily disable custom rule sets and use basic global proxy mode as a comparison. If global mode restores connectivity, the node path is probably healthy and the issue is in rule matching. If global mode still fails, continue checking node parameters and DNS. When restoring split routing, start with a small number of explicit rules: send private addresses and the local network direct, then add confirmed domain rules, and finally set a fallback outbound. Rules are usually matched in order, so a broad rule earlier in the list can mask a precise rule later on.

Also verify that every outbound tag actually exists. Tags referenced by rules must exactly match the proxy, direct, and block outbounds in the current configuration; differences in capitalization or spelling can cause loading failures or fall back to the default outbound. The outbound structure managed by the client may change after a subscription update, so do not mechanically copy tags from a different complete configuration. If the core log says outbound not found, invalid field, or configuration parsing error, restore the client-generated default configuration first and then add custom items one by one.

Restore the network state

After an abnormal client exit, the system proxy may still point to a local address whose port is no longer listening, making the browser appear completely offline. Reopen the client and use “Clear system proxy,” or disable the manual proxy in the system network settings, then test a direct connection again. If virtual network mode is enabled, stop it normally so the routing table and DNS settings can be restored; force-ending the process may leave temporary network state behind. Once restored, restart the client, verify direct access, then verify an explicit local proxy, and only afterward enable system-wide takeover.

If only LAN resources are inaccessible, check whether private network ranges are being proxied. Home routers, printers, storage devices, and company services usually use private addresses and should use a direct outbound. Place private-address rules before the fallback proxy rule and confirm that virtual network mode is not sending LAN discovery traffic to the remote side. If only one site fails, use a private browser window to rule out cache and extension effects, and check which outbound the domain ultimately matched in the log. These checks usually turn “no internet access” into a specific port, routing, DNS, or node issue.

3. Node Timeouts and Handshake Failures

Understand timeouts, refusals, and handshake errors

A timeout in the node list only means that the test request did not finish within the allotted time; it does not by itself prove that the server is permanently unavailable. A connection timeout usually means the TCP or UDP path to the node address and port was not established in time. A refusal means the address is reachable but no service accepted connections on that port. A reset means one side actively interrupted an established path. A TLS handshake error requires checking the server name, transport layer, security parameters, and system time. Different errors point to different layers and should not all be labeled “node failure.”

Run a real connection test on two nodes from the same subscription. If every node times out on the current network but works after switching networks, check the local egress, firewall, or routing path first. If only one node times out while others work, the issue is more likely its address, port, or remote service. If the same node fails across multiple devices and networks, contact the configuration provider to verify its status and parameters instead of repeatedly changing client settings.

Verify node parameters one by one

When importing a node manually, the address, port, user identifier, protocol, security layer, transport, server name, and path must be consistent as a set. Fields from VLESS and VMess cannot be mixed arbitrarily; WebSocket, gRPC, and TCP also use different paths, service names, and headers. The most common issue is not a missing field, but an old node configuration copied with only its address and port changed, leaving an incompatible server name or transport parameter behind. Compare the client editor with the original configuration field by field instead of relying on the node label.

When TLS is enabled, the server name is normally used for certificate validation and the handshake, so it should not be casually replaced with the node IP. A significant system-clock error can make certificates appear not yet valid or already expired. If the log contains certificate, handshake, server name, or verify failed, correct the system time first, then verify the server name and security settings. Do not hide mismatched parameters by disabling necessary validation; obtain configuration that matches the server instead. With security methods such as REALITY, keep the public key, short ID, server name, and flow parameters consistent as well.

Latency tests do not prove usability

ICMP ping, TCP connection, proxy handshake, and download speed tests measure different stages. A server may ignore ping while its proxy port works; a TCP port may accept connections while protocol authentication fails; a real-connection latency test may be low even though sustained throughput is limited. When choosing a node, first use the client’s real-connection test to verify the proxy handshake, then use actual webpages and file transfers to verify stability. For the differences between the three test types, see How V2Ray latency tests work.

Avoid excessive concurrency during testing. Measuring many nodes at once consumes local connections, DNS queries, and network egress. Some routers also limit large bursts of new connections, which can make an entire batch time out. Test a small number of nodes sequentially, wait for the previous connections to close, and then compare the results. On mobile networks, signal changes, background power saving, and network-type transitions can distort short tests, so retest after the connection is stable.

Confirm address resolution and protocol network requirements

When the node address is a domain, the client must resolve it first. If the DNS rules require that lookup to go through a proxy that has not been established, startup can become circular: without the node there is no DNS path, and without DNS the node cannot be reached. Temporarily use a reliable direct DNS path to resolve the node domain while keeping destination-domain resolution under the intended policy. Features that use UDP also require support from the local network, client inbound, remote node, and outbound path; checking a UDP box in the client is not enough.

The final record should state whether the node parameters came from a complete import, whether other nodes in the same group work, whether switching networks restores connectivity, and whether the error occurred during TCP connection establishment or the protocol handshake. If the issue affects one node across networks, keep only the error type in the log and do not expose credentials. If all nodes fail only on the current network, focus on the local firewall, router, DNS, and network egress instead of editing every node.

4. Subscription Updates and Import Failures

First determine whether the download or the parsing failed

A subscription failure has at least three stages: the client did not obtain the subscription content; it obtained content but could not parse it; or parsing succeeded but the nodes did not enter the current group. Check the log and message text during an update. HTTP timeouts, connection failures, and domain-resolution failures usually belong to the download stage. Messages mentioning base64, JSON, YAML, or unsupported scheme usually belong to content parsing. If the update completes but the list does not change, check the selected group, deduplication, filters, and whether the subscription content actually changed.

Confirm that you are updating the subscription group currently being viewed. v2rayN supports multiple subscription groups, and the node list may still be showing another group; the update command may also apply only to the selected group. Do not repeatedly import the same URL into groups with identical names. First inspect the group properties, including the subscription URL, enabled status, and update result. Android clients likewise distinguish single-node imports, bulk clipboard imports, and subscription management; these do not automatically merge into one update source.

Check the subscription URL for completeness

When copying a subscription URL from a chat app or webpage, leading or trailing spaces, line breaks, escape characters, and truncated query parameters can all cause the request to fail. Confirm in the subscription editor that the URL is continuous and complete from the scheme through the final parameter. Some URLs contain temporary tokens or device parameters; missing one character may return an unauthorized response or empty content. Do not paste the subscription URL into public logs, screenshots, or online analysis tools because it usually grants access to configuration data.

If the client supports updating subscriptions through a proxy, test both “update directly” and “update through the current proxy.” When the current network can reach the subscription service directly, the direct path is simplest. If an existing node is required, at least one usable node must already be available. If every old node in the only subscription is unavailable, updating through the proxy creates a deadlock. Obtain a directly reachable new URL or an independent configuration from the provider instead of refreshing the same failed request.

Handle successful updates with no new nodes

Check the update time and log first to confirm that an update actually occurred; do not look only at the node count. The subscription service may return the same content as before, and the client may deduplicate nodes by identifier, so an unchanged count can be normal. Check whether name filters, regular-expression filters, protocol restrictions, or options that remove old nodes are enabled. An overly broad filter can exclude every new node after parsing; a syntax error may cause some clients to retain the old list while reporting an update failure.

Export the currently usable configuration before modifying a subscription group, then create a temporary group and import the same subscription. This removes the effects of old caches, filters, and duplicates. If the temporary group is also empty, focus on the returned subscription content. If it contains nodes while the original group does not, focus on the original group’s filters, sorting, and update settings. After comparing them, decide whether to replace the original group. Do not delete the only usable nodes at the start.

Recognize format and client capability differences

A subscription may be a collection of protocol links or a structured configuration. The client can parse only the formats and fields it supports. Importing a complete core configuration as an ordinary subscription, or putting a single share link into a subscription URL field, can produce a format error. Confirm that the provider’s stated import method matches the current client. v2rayNG uses the Xray core, while v2flyNG uses the v2fly core; their support for some newer fields and transport combinations may differ. The same content being importable in one client does not guarantee that another client will accept it.

{
  "remarks": "example-subscription",
  "url": "https://example.com/subscription?token=xxxx",
  "enabled": true
}

The structure above only illustrates the logical fields to verify. Add the actual subscription through the client interface rather than treating the example as a client configuration file. When a parsing error occurs, keep the field name near the reported line and confirm that the client and core came from the installation entry on the current download page. Do not invent version numbers to judge compatibility; rely on the features and logs actually shown by the client.

If subscription requests fail intermittently, retry after a short interval on the same network and compare direct updates with proxy-based updates. Repeated rapid refreshes may trigger server-side request limits and make the logs difficult to read. The final record should answer: did the request succeed, was the returned content parseable, did the nodes enter the target group, and did filters remove the results? For more short questions, continue checking the “Installation and configuration” category in the Help Center.

5. Connected but Slow

Measure latency, bandwidth, and stability separately

Do not judge slow speeds by the milliseconds shown in the node list alone. Latency affects short-connection setup and interactive response; bandwidth determines sustained transfer speed; packet loss and jitter determine whether video, calls, and long-lived connections remain stable. A low-latency node may have limited egress bandwidth, while a slightly higher-latency node may download faster over time. First open a fixed webpage and observe initial response, then run a sustained transfer, and finally watch for repeated interruptions over several minutes. Record these three observations separately instead of replacing the whole assessment with one speed test.

For a useful comparison group, keep the device, network, destination resource, and test time similar, changing only the node. Measure the available bandwidth of the direct connection first, then test two nodes on different routes. If the direct connection is already slow, address Wi-Fi signal, mobile-network quality, and local usage. If all nodes cluster around the same low speed, check device performance, virtual network mode, and remote egress. If only one node is significantly slower, route congestion or poor egress quality is more likely.

Rule out local resource use and concurrency

Sync tools, system updates, cloud drives, video playback, and other devices can consume upload or download capacity. When upload is saturated, acknowledgments cannot be sent promptly and downloads may also stutter. Pause high-traffic tasks before testing and watch network usage in the router or system task manager. A browser with many open pages, a high-concurrency downloader, or parallel testing of every node can also consume connections and CPU, making results unstable.

The client core handles encryption, transport encapsulation, route matching, and DNS. Low-power devices may saturate their CPU under high throughput, causing speed to stop increasing beyond a certain point. Observe system resources: if one core remains fully loaded during transfers, simplify complex rules, reduce unnecessary logging, and compare system proxy mode with virtual network mode. Do not change unfamiliar transport parameters just to chase speed. The client configuration must match the remote service; one-sided changes often cause connection failures instead.

Check whether routing is taking a detour

A speed issue is sometimes a routing issue. Local or regional resources that should go direct may be sent through the proxy, adding path length and egress load. A destination that should use the proxy may be incorrectly sent direct and repeatedly retried. Check the destination domain, resolution result, and final outbound in the log to confirm that the rule match is expected. With geosite and geoip split routing, domain and IP rules may produce different decisions, and rule order determines the final result.

Use global proxy mode first to measure the node’s ceiling, then restore split routing. If global mode is fast but split routing is slow, check DNS and rule matching. If both are slow, continue checking the route and device. If only the first page load is slow and later requests work, common causes include DNS lookup, the first TLS handshake, or connection setup. If the transfer starts fast and then declines, congestion, packet loss, device temperature, or bandwidth limits are more likely. For practical routing configuration, see geosite and geoip split-routing in practice.

Use a repeatable testing method

Do not use several speed-test sites at once and mix their results. Choose a fixed resource and test the direct connection, node A, and node B at similar times. Repeat each state two or three times and record the median performance rather than the best result. Keep the routing mode consistent and prevent browser cache from affecting download results. If the destination schedules traffic differently for different egresses, cross-check with another stable resource so a single-site bottleneck is not mistaken for node speed.

Limit concurrency in real-connection latency tests and run large node lists in batches. If the log frequently contains retry, broken pipe, reset, or idle timeout, the path is unstable even if average speed looks acceptable. Prefer nodes with less packet loss and fewer reconnects rather than simply choosing the lowest latency. Video and interactive applications generally prioritize stability, while long file transfers prioritize sustained bandwidth, so the selection criteria cannot be identical.

After troubleshooting, you should be able to identify whether the bottleneck is the direct network, device processing, a routing detour, the first DNS lookup, one node’s route, or the destination resource. If it varies by time of day, keep comparisons from different periods. If it varies by network, compare Wi-Fi with mobile data. If it varies by client mode, inspect the virtual interface and rule complexity. This conclusion is more useful for follow-up work than simply saying “the speed test is low.”

6. DNS Resolution Errors, Poisoning, and Leaking Mismatches

Recognize typical DNS failure patterns

DNS problems often appear as a domain failing while a known IP responds directly, different results for the same site in different applications, changed resolution addresses after switching proxy modes, or log messages such as lookup, resolve, no such host, SERVFAIL, and NXDOMAIN. The node itself may connect while the destination domain resolves to an unsuitable address, ultimately causing a timeout or certificate-name mismatch. Always separate resolution of the node domain from resolution of the destination domain; they may use different paths.

Clear system and browser caches first, then repeat the lookup. A browser may use its own secure DNS and not follow system or client settings; the system may also cache an old answer. Disable the browser’s independent DNS or record its state, then compare a system query tool with the client log. On Windows, use nslookup; on macOS and Linux, use dig or nslookup. Different results do not automatically mean that one side is wrong. Check whether the request should ultimately be handled by direct DNS or proxy-side DNS.

nslookup example.com
nslookup example.com 1.1.1.1

dig example.com
dig @1.1.1.1 example.com

Understand local and remote resolution

With local resolution, the device obtains an IP first and routing rules then process the connection. With remote resolution, the domain is handled on the proxy side. The former makes IP-based routing easier but depends on local DNS results; the latter avoids letting the local resolution path affect the destination domain, while the client still has to resolve the node address and some direct domains. Mode names vary by client and core configuration, so do not judge from a single switch label. Use the log to confirm whether the domain was resolved locally or remotely.

When routing rules contain both domain and IP conditions, remember that the resolution strategy determines whether an address is available for IP-rule matching. Domain-only matching may not require early resolution; geoip matching may require the core to resolve first. The wrong strategy can produce a situation where neither the domain rule nor the IP rule behaves as expected. Define the goal first: send local domains and private addresses direct, route selected domains to a specified outbound, and send everything else to the default outbound. Then choose a resolution path that matches that design.

Prevent startup dependencies and resolution loops

If the node address is itself a domain and the configuration requires every DNS query to go through that node, resolution becomes circular. Provide bootstrap resolution that works before the proxy is established, or send the node domain through an explicit direct DNS path. Bootstrap DNS should handle only the small number of lookups required to establish the proxy and should not be confused with destination-domain policy. If the log repeatedly queries the node domain and starts another DNS request before the connection is established, inspect this dependency.

Virtual network mode may also take over system DNS. After an abnormal exit, network change, or wake from sleep, the system may retain an unreachable DNS address, making resolution fail even after the proxy is disabled. Stop virtual network mode normally, then check whether the network adapter’s DNS has returned to automatic or its previous settings. Do not let multiple network tools modify DNS while the client is running, or it will be difficult to determine which configuration is active.

Use logs to verify the final answer

After changing DNS, do not judge it by whether a webpage happens to open once. Clear the cache, query a fixed domain, record the returned address, and confirm in the client log which outbound the domain matched. If a domain has multiple addresses, short-term changes may reflect normal load balancing. Focus on whether the address type and outbound match the routing design. The configuration is valid only when the resolution result, route match, and final connection agree.

When one domain keeps failing, compare its root domain with its subdomains and check for a dedicated domain rule, a hosts override, or cached data. Hosts entries usually have high priority, and an old entry can make every DNS setting appear ineffective. If the error occurs only in one browser, clear that browser’s DNS and connection caches. If every application behaves the same, return to the system and client layers. Changing DNS providers is useful as a comparison, but does not replace confirming the resolution path.

DNS repair is accepted when the client can connect to the node after a cold start, system queries follow the expected resolution path, the browser and command line produce the same result through the same proxy entry point, and system DNS recovers after network changes, wake from sleep, and a normal exit. If only virtual network mode fails while ordinary system proxy mode works, continue checking DNS takeover by the virtual interface, route priority, and system permissions.

7. System Proxy Settings Not Taking Effect

Confirm whether the application follows the system proxy

The system proxy is not a universal tunnel that every program uses automatically. Browsers and some desktop applications usually read it, while command-line tools, games, background services, and programs with their own network stack may ignore it. If the browser works but one application connects directly, check whether that application supports the system proxy, stores a manual proxy, or requires separate HTTP or SOCKS settings. If it clearly ignores the system proxy, consider the client’s virtual network mode, but understand its permissions, routing, and DNS takeover before enabling it.

A browser proxy extension can override system settings. If it points to an old port, old protocol, or another proxy program, v2rayN’s system proxy status does not determine the browser’s actual path. Temporarily disable the extension and use the browser’s default network settings. If the problem disappears, configure the extension again. Enterprise policies may also lock proxy values. Even when the system settings are visible, the value read by applications may be policy-controlled, so check whether the system proxy page indicates that the device is managed by an organization.

Verify the protocol and listening address

HTTP and SOCKS proxies cannot be interchanged based on the port number alone. The system proxy usually requires an HTTP entry, while some tools can use SOCKS directly. Confirm each inbound’s protocol, listening address, and port in the client settings, then configure the application accordingly. Listening on 127.0.0.1 means that only the local machine can connect. Allowing LAN connections may make the client listen on all interfaces, but that is not required for the local system proxy to work. In normal use, do not expose LAN listening merely to fix a local proxy.

Use the following method to verify an explicit HTTP proxy. If the command succeeds but the browser fails in system proxy mode, inspect the system proxy entry or browser override. If the command is refused when connecting to the local port, check the core process and port. If the local connection succeeds but the remote request fails, investigate the node, routing, and DNS.

curl -I --proxy http://127.0.0.1:10809 https://example.com/
curl -I --socks5-hostname 127.0.0.1:10808 https://example.com/

The example port is for illustration only; use the value in the client’s current settings. --socks5-hostname resolves domains through the SOCKS path and is useful for comparison with local resolution. Do not run multiple programs that automatically set the system proxy at the same time. They may overwrite the system value in turn, leaving the interface state inconsistent with the actual registry or network-service settings.

Handle proxy leftovers after an abnormal exit

After the client is force-closed, the system shuts down unexpectedly, or the core crashes, the system proxy may still point to a local port. Every application that follows the system proxy will then fail, making the network appear disconnected. Restart the original client, clear or disable the system proxy, and exit normally. You can also disable the proxy manually in the system network settings. After direct access is restored, start the client and configure it again. Do not immediately delete all configuration while the network is down, or you will lose the evidence needed to identify the leftover port and original settings.

On Windows, also distinguish between accounts and permission contexts. Programs started with different privileges may read different environment variables or settings, and background services may not use the proxy of the current desktop account. On macOS, proxy settings are stored per network service, so Wi-Fi and other interfaces may have different configurations. After switching interfaces, verify the active network service’s proxy state. Linux desktop environments may simultaneously use desktop proxy settings, environment variables, and application-specific settings; check them layer by layer.

Environment variables and command-line programs

Command-line programs commonly read HTTP_PROXY, HTTPS_PROXY, ALL_PROXY, and NO_PROXY. These variables may come from the current terminal, user profile, system service, or container environment. If a terminal still contains an old port, command-line requests can fail even after the desktop system proxy is updated. Check the variables and reopen the terminal so the new process reads their latest values. Internal domains and local addresses usually belong in the no-proxy range, but keep exclusions precise; an overly broad exclusion can send requests that should use the proxy directly.

set HTTP_PROXY
set HTTPS_PROXY

env | grep -i proxy

Before clearing variables, record where they came from. Otherwise, a temporary change in the current terminal may disappear and the old value will return on the next launch. Containers and subsystems have independent network namespaces, so 127.0.0.1 may refer to the container itself rather than the host. Use a host address that the environment can reach and confirm that the client allows connections on that interface. This is an application network-boundary issue, not a node-protocol issue.

Confirm that the core port is actually listening; the system proxy points to the same port with the correct protocol; no browser extension overrides it; command-line variables contain no old values; the proxy can recover after an abnormal exit; and applications that ignore the system proxy have an explicit solution. If you need to reinstall the client, choose the appropriate platform from the client download page first. Before uninstalling, record the current ports, groups, and routing settings so configuration differences are not mistaken for program defects.

8. Client Startup Failures, Crashes, and Core Exits

Separate the UI process from the core process

Graphical clients such as v2rayN usually handle configuration management, subscriptions, the system proxy, and the interface, while Xray or the v2fly core process handles actual connections. If the interface opens but cannot connect, the core may not have started. If the interface exits immediately, check the runtime environment, configuration files, permissions, and program files first. Seeing only the UI process in Task Manager or the system process list does not prove that the core is running normally. The point where the log stops—before or after “starting core”—also changes the troubleshooting direction.

Fully exit the client first, confirm that no UI or core processes remain, and start it once again. Do not click Start repeatedly, or multiple instances may compete for configuration files and listening ports. If the client says that another instance is already running, end the leftover process in Task Manager, wait for the port to be released, and start again. If it exits every time after loading a particular configuration, export a backup of the current configuration and test with a simple known-good configuration.

Check configuration parsing and write permissions

When editing JSON manually, an extra comma, incorrect quote, or wrong field type can prevent the core from loading. Messages such as failed to parse, invalid character, unknown field, or failed to load config often identify the field location. Restore a default client-generated configuration through the interface and add custom DNS and routing items one at a time instead of layering changes onto a broken file. The minimal JSON structure below is syntactically complete and only illustrates the relationship between brackets and arrays; it contains no directly usable node.

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [],
  "outbounds": [
    {
      "protocol": "freedom",
      "tag": "direct"
    }
  ]
}

If the configuration directory is not writable, subscription updates, log creation, and saved settings may all fail. Check that the client directory and user-data directory are writable by the current account, and avoid running directly from a read-only location. If security software quarantines core files, the interface may report that the core is missing or exit immediately after launch. Check the system security records, confirm the file source and this site’s download entry, and then follow local management policy. Do not obtain an individual core file from an unknown source, as it can create an incompatible UI-and-core combination.

Handle port conflicts and duplicate instances

When the core exits immediately after starting, a local port conflict is a common cause. The log may contain bind, listen, or address already in use. Identify the process using the port and determine whether it is an old client instance, another proxy program, or a system service. If it is a leftover instance, end it normally and restart. If the port belongs to a required service, change the HTTP and SOCKS ports in the client and update the system proxy, browser extensions, and command-line environment variables as well. Changing only the client port without updating its users turns a “crash” into a “proxy not taking effect” problem.

Multiple user accounts, remote-desktop sessions, or startup tasks may also launch separate instances. Check startup items and scheduled tasks to ensure that only one client is responsible for setting the system proxy. If different configurations must run in parallel, assign each instance its own data directory, logs, and listening ports. This is not recommended for ordinary troubleshooting because the results become difficult to attribute.

Recover from a clean state instead of deleting blindly

Before recovery, back up subscription groups, manual nodes, and custom routes, but do not place subscription URLs or node credentials in a public location. Disable the system proxy and virtual network mode, exit the client normally, and rename the existing configuration directory as a backup. Start the client to generate a fresh default configuration and confirm that both the interface and core work. Then import items one by one: a single node first, the subscription group next, and routing and DNS last. The layer that causes another crash is the one to investigate.

If a fresh configuration still will not start, investigate the runtime environment, system permissions, program architecture, and security-software records. On macOS, confirm that the system allows the application to open. On Linux, start it from a terminal to observe missing dependencies and permission errors. On Windows, check Application events and client logs. Keep the failing module, exit stage, and error code in any report, but remove personal paths, subscription content, and credentials.

If crashes occur only during subscription updates or large-scale speed tests, reduce concurrency and watch memory and disk space. If they occur only after waking from sleep, check network-interface changes and old core processes. If they occur only in virtual network mode, check drivers, permissions, and conflicts with other virtual interfaces. After troubleshooting, identify whether the problem is in the UI, core, configuration parsing, ports, permissions, or runtime environment before deciding to repair the configuration or reinstall. Do not attribute every abnormality to the client version.

9. Android Connectivity and Background Operation

Confirm virtual network authorization and the active client

On Android, v2rayNG and v2flyNG typically take over traffic through the system’s virtual network interface. The first connection requires system authorization. If authorization is denied, another virtual-network app is using the interface, or the system revokes access after a reboot, the client may show that it is starting without actually taking over traffic. Stop other tools that use the same system interface, restart the current client, and confirm the authorization prompt. A connection icon in the status bar is only a clue that the interface exists; verify the node path through logs and an actual request.

Do not leave two clients connected at the same time. v2rayNG uses the Xray core, while v2flyNG uses the v2fly core, and their supported configuration fields may differ. When importing the same subscription into both clients for comparison, stop the first connection before starting the second. The system generally allows only one interface to take effect, or the result may be mistaken for a node failure. You can use v2rayN on desktop as a cross-check, but account for differences in Wi-Fi, mobile networks, and DNS paths across devices.

Handle background termination and lock-screen drops

Some Android systems restrict background processes, lock-screen networking, and battery use. A typical pattern is a connection that works in the foreground, drops after several minutes with the screen locked, and recovers when the client is reopened. In system app settings, allow the client to run continuously in the background, disable strict battery restrictions for it, and confirm that the system does not automatically remove its notification or service. Menu names vary by device; look for settings such as “Battery,” “Background usage,” “Auto-start,” and “App launch management.”

After configuring these settings, do not rely only on the client button state. Connect, visit a fixed webpage, lock the screen, wait, unlock it, repeat the request, and inspect the log timeline. If the log stops completely during the interval, the process was likely suspended. If the log continues but the connection is rebuilt, the network interface may have changed during sleep. If the request appears in the log and the node then times out, continue checking the network path. A persistent notification often helps the system recognize the running network service, so do not casually disable its notification category.

Switching between Wi-Fi and mobile data

When switching from Wi-Fi to mobile data, the device IP, DNS, maximum transmission unit, and network capabilities all change. Existing connections usually need to be rebuilt, so a brief failure is part of the transition. If there is still no connectivity afterward, stop and restart the client so the virtual interface binds to the new network. When switching back to Wi-Fi, test again, especially on public networks that require a web login: pause the proxy, complete network authentication, and reconnect afterward.

If Wi-Fi works but mobile data times out, check whether the node address resolves over mobile data, whether the mobile network access point restricts certain connection methods, and whether another node in the subscription works as a comparison. If mobile data works but home Wi-Fi fails, check the router’s DNS, firewall, and other devices on the same network. Do not change node parameters at the same time as switching networks, or you will not know whether recovery came from the network or the configuration.

Per-app proxy and bypass settings

Android clients often provide per-app proxy settings. Make sure you know whether the current mode is “proxy only selected apps” or “bypass selected apps.” These modes work in opposite directions. Choosing the wrong one can make the browser work while other apps connect directly, or make only a few apps fail. Temporarily disable per-app settings and give all applications the same path. Once the basic connection works, add apps one by one and test them. App identifiers can change after an update or reinstall, so review the list again.

LAN applications, casting, printing, and device discovery may need to bypass the proxy, but the virtual-interface route still controls the actual traffic. If LAN access fails, confirm that the client allows LAN bypass and that private addresses use a direct path. Do not use an overly broad bypass range that covers all traffic. Add one item at a time and verify it with the target app. If the app has its own proxy or secure DNS, temporarily restore its defaults so it does not conflict with the client’s virtual network settings.

Mobile logs and final acceptance checks

Mobile log collection should cover connection startup, network switching, screen-lock recovery, and the time when the failing app sends a request. Record whether the system shows a virtual-network connection, whether the client service is still running, whether the request enters the log, and whether the node reconnects. Before sharing logs, remove subscription URLs, user identifiers, and complete server details. If the issue affects only one app, also record whether it uses independent DNS, whether it is selected by per-app rules, and whether the browser comparison works.

Final acceptance should include at least four checks: continuous foreground access works; access resumes after unlocking; switching between Wi-Fi and mobile data recovers automatically or after one reconnection; and per-app rules behave as intended. If v2rayNG and v2flyNG behave differently with the same configuration, verify the compatibility of its core fields before choosing a client. Do not treat the client name as the only cause. To obtain the installation entry again, return to the Android client downloads.

If the issue remains unresolved after all nine chapters, reduce it to “which layer fails, which comparison changes the result, and what error appears in the log.” For example: “The explicit local proxy works but the system proxy does not,” “The node times out on Wi-Fi but works on mobile data,” “The subscription downloads successfully but parses to an empty result,” or “Core logs stop after the screen is locked.” Then search the relevant category in the Help Center, or return to the Getting Started guide and rebuild a minimal working configuration. The goal of systematic troubleshooting is not to try more settings, but to reach a verifiable conclusion with fewer variables.