For users dealing with node test timeouts, connection failures after startup, or sudden failures after switching networks. First distinguish the local listener, server port, and protocol handshake. Then check the clock, transport, and TLS settings; finally, use logs from the same request to pinpoint the issue. This guide uses v2rayN on macOS and v2rayNG on Android. Port numbers are examples—replace them with the values configured in your client.
1. Identify where the timeout occurs
A “node timeout” can have several causes. A failed TCP connection, TLS handshake error, proxy authentication failure, or unresponsive test URL can all appear as a timeout. Note what you were doing when it occurred: updating a subscription, testing the server’s actual connection latency, or opening a webpage in a browser. A failed subscription download does not mean every node in it is down.
For troubleshooting, stick to one node, one test URL, and one connection mode. On desktop, turn off TUN first and test the local proxy explicitly. On Android, start only v2rayNG to avoid another VPN service taking over the connection. Don’t change DNS, routing, the node, and the core all at once; even if things start working, you won’t know which change fixed it.
| Symptom | Check first | Does not prove |
|---|---|---|
| Local proxy port refuses the connection | Whether the core is running and which address and port it listens on | That the remote node is down |
| Server TCP port times out | DNS resolution, port, network route, and firewall | That the UUID or password is wrong |
| Port is reachable, but the actual request fails | TLS, transport, authentication, and server outbound connectivity | That the entire connection path is working |
| Only one test URL fails | Test URL, destination website, and routing rules | That every proxy request is failing |
2. Check your system clock and basic network
Check the clock before investigating certificates. On macOS, open System Settings → General → Date & Time, turn on automatic time, and verify the date, year, and time zone. On Android, go to Settings → System → Date & time; on some devices, this is under More settings. Turn on automatic time and time zone. Restart the client after correcting the clock, then try connecting again.
An incorrect system clock can affect certificate validity checks and VMess authentication. Changing only the time zone won’t help if the actual time is still wrong. If automatic time is enabled but the clock is still significantly off, first check whether the system can reach a time server. Don’t hide a clock problem by disabling certificate verification.
-
Keep the test conditions consistent
Select one node and note the network, test URL, and time of the error. Stop other proxy or VPN services so they can’t take over the request.
-
Correct the system clock
Turn on automatic time in the system’s Date & Time settings. Once the date and time are correct, quit and reopen v2rayN or v2rayNG.
-
Check your direct connection
Pause the proxy and visit a website that’s accessible on your current network. If public Wi-Fi requires a sign-in page, complete that first. Don’t change node settings until the basic connection is working.
-
Test on another network
Keep the same node and settings, then switch to a mobile hotspot. If it works only on the new network, investigate port restrictions, DNS, or outbound policies on the original network.
3. Test the local listener separately from the server port
The local listening port and the node’s server port serve different purposes. The local port lets your browser or command line connect to the client; the remote port is used by the client to reach the server. The examples below use local SOCKS port 10808 and remote TLS port 443. These aren’t necessarily the default values for every installation.
In v2rayN, check the local listening options under Settings → Parameter settings. Section names may vary by version, so follow the labels shown in your app. Once the core is running, open Terminal on macOS and run the commands below. Use the second command only if the port actually provides a SOCKS service; don’t enter an HTTP-only port as a SOCKS proxy.
# Check whether a process is listening on the example local port
lsof -nP -iTCP:10808 -sTCP:LISTEN
# Send an HTTPS request through the local SOCKS proxy explicitly
curl --proxy socks5h://127.0.0.1:10808 \
--connect-timeout 5 --max-time 10 \
--output /dev/null --show-error --verbose https://example.com/socks5h lets the SOCKS proxy resolve the destination hostname, helping rule out differences in how the application resolves it for this request. It does not force all DNS traffic to go through the remote server: the core and system settings still determine how the node server address is resolved. You can replace the test URL with any HTTPS site you need to reach.
- No listener found: Check the core startup logs first. If the configuration failed to load or the port is already in use, the local proxy may never have started.
- Local proxy is reachable, but requests time out: Check the remote address and port, then verify the handshake settings.
- Explicit proxy works, but the browser doesn’t: Check the system proxy, browser proxy extensions, and routing. Don’t rebuild the node right away.
- Check the remote port: On macOS, run
nc -vz -G 5followed by the actual server hostname and port. A successful TCP connection confirms that the port is reachable, not that the protocol or credentials are valid.
Takeaway: Use an explicit proxy to narrow down the issue
If the same node works with the curl request above, leave its settings unchanged for now. Fixing the path from the app to the client is easier to verify than changing the server configuration at the same time.
4. Check transport, TLS, and SNI settings one by one
If the port is reachable but requests fail, open the node editor and compare each setting with the original configuration from your service provider. In v2rayN, you can usually double-click a node to edit it; in v2rayNG, use the edit control next to the node in the configuration list. For subscription nodes, update the subscription before checking settings. Save the original configuration before making manual changes so a later update won’t overwrite them.
| Setting | What to check | Common mistake |
|---|---|---|
| Protocol and credentials | Protocol type—VMess, VLESS, Trojan, or Shadowsocks—and the corresponding UUID, password, or encryption method | Assuming nodes with the same address and port are the same type |
| Transport type | TCP, WebSocket, gRPC, and so on; it must match the server | Switching transport types at random as if they were a speed setting |
| WebSocket | Path, Host, and TLS toggle | Missing the leading slash in a path or deleting path parameters without checking |
| gRPC | Service name, TLS, and the ALPN required by the server | Entering a WebSocket path as the service name |
| TLS | Server name (SNI), certificate chain, and validity period | Changing the SNI to an IP address after changing the connection address to an IP |
| REALITY | Public key, shortId, serverName, fingerprint, and applicable flow | Copying only the UUID and missing the security settings |
SNI is the server name used during the TLS handshake and doesn’t have to match the connection address. The connection address may be an IP, while SNI still needs to be the domain specified by the server. A WebSocket Host belongs to the HTTP layer. Even when it often matches SNI, the two fields are not interchangeable.
5. Use outbound logs from the same request to pinpoint the issue
Open the log panel in the v2rayN main window, or select Logs from the v2rayNG menu. Clear old entries or note the current time, then run a single test. If the default log level doesn’t show the cause, switch briefly to debug level, reproduce the issue, and restore the previous level. Menu names vary by version; look for the log-level option rather than relying on screenshots from another release.
Error: connection refused
Cause: Nothing is listening on the destination port, or a device along the route is actively refusing the connection. First determine whether the error refers to a local or remote address.
Fix: For a local address error, check the core and listening port. For a remote address error, verify the server port and ask your service provider to check the listening service and firewall.
Error: i/o timeout
Cause: A read or write operation didn’t complete before its deadline. This message alone can’t distinguish packet loss, an unreachable port, or a handshake that received no response.
Fix: Check the destination address and operation in the preceding log entry. Test the port first, then reproduce the issue on another network with the same settings.
Error: x509: certificate has expired or is not yet valid
Cause: The certificate’s validity period doesn’t match the system clock. The local time may be wrong, or the remote certificate may have expired.
Fix: Correct the system clock first. If the error persists with the correct time, give the error timestamp to your service provider and ask them to check the certificate deployment.
Error: tls: handshake failure
Cause: The other end rejected TLS negotiation. Possible causes include SNI, protocol negotiation, or a connection to the wrong service.
Fix: Compare the port, TLS setting, SNI, and ALPN with the original configuration. Simply increasing the timeout won’t fix this.
Error: no such host
Cause: A hostname in the log could not be resolved. It may be the node server address or the destination website.
Fix: Identify the hostname first, then check its spelling, resolver reachability, and the relevant DNS routing. Avoid sending all DNS queries through the same route.
EOF in the logs only means the connection was closed; it does not prove that the credentials are invalid. Check the handshake entries before it and whether the failure occurs with only one node. Before sharing logs, redact subscription links, UUIDs, passwords, tokens, and personal network details. Include only the relevant error stage, time, and parameter types.
6. Check core compatibility and Android background restrictions
v2rayN and v2rayNG are clients; the core handles the actual protocols. Being able to import a field in the interface doesn’t mean the current core supports it. v2rayNG uses the Xray core, while v2flyNG uses the v2fly core; don’t assume they support extended settings in exactly the same way. For REALITY or newer transport fields in particular, check both the client and core versions.
- Record both versions: Find the client version under About and the core version in the startup logs. Don’t just write “latest”—installation sources and update dates can differ between devices.
- Check startup errors: If you see an unknown field, a transport initialization failure, or a configuration parsing error, address compatibility and configuration first instead of repeatedly testing the connection.
- Update the client and its bundled core: Back up the configuration, then update the client and its matching core. Don’t overwrite files in an older installation directory with an incompatible core.
- Check Android battery settings: Long-press the v2rayNG icon, open App info → Battery, and allow the necessary background activity using the options available on your device. Check this first only if the connection fails after the screen locks or the app goes into the background.
- Distinguish an app stopping in the background from a handshake failure: If the VPN indicator disappears or the service stops, investigate the process or system management. If the service is still running but the logs keep showing handshake errors, check the node settings.
Takeaway: Update only when you’ve identified a compatibility issue
If the port is unreachable, fix the network path first. Update the client and matching core only when the logs clearly show an unsupported configuration. Making updates only when the evidence points to them avoids introducing new variables.
7. Retest one variable at a time and record reproducible results
Change one setting at a time, restart the core, and use the same test URL. Three consecutive successes are a useful initial check, but don’t guarantee long-term stability; keep testing on the original network, in the original app, and during your usual usage hours. A longer timeout can tolerate slower responses, but it won’t fix an incorrect SNI, invalid credentials, or a closed port.
| Result | Next step |
|---|---|
| Same node works on a hotspot but fails on the original network | Keep the node settings and check the original network’s outbound route, DNS, and port policies |
| Other nodes work on the same network; only one fails | Update the subscription and ask your service provider to confirm the node’s status and settings |
| Explicit proxy works, but system proxy access fails | Check the system proxy port, app proxy settings, and browser extensions |
| Fails on multiple networks despite verified settings | Send redacted logs and version details to your service provider and ask them to check the server logs |
When reporting a problem, include the time and time zone, OS version, client version, core version, protocol and transport type, and comparison results such as “fails on the original network, works on a hotspot.” Don’t send your full subscription link or post node passwords in public discussions. A reproducible request with its corresponding logs is more useful for troubleshooting than a screenshot that just says “timeout.”