Node HandbookNODE HANDBOOK中文
v2rayN · macOS

v2rayN on macOS: port already in use after switching cores

A latency number is not proof that the main core is listening. Under TUN, switching from a sing-box node to an Xray node can leave the old listener holding the local port, and the new core fails to bind it.

Node Handbook editorial team ·

The conclusion first

A latency number appears in the interface and does not mean the current main core successfully bound its local port. Close TUN, restore ordinary networking, note the exact port from the error, and find out which process holds it. Consider terminating a leftover core only after confirming it belongs to this v2rayN session — never terminate unknown processes by name in bulk.

One public record you can check

v2rayN issue #10523 documents a macOS Arm64 case on v2rayN 7.25.6 with Xray 26.10.31 and sing-box 1.14.4: with TUN enabled, switching from a Hysteria2 node (sing-box) to a VLESS node (Xray) left the old sing-box holding 127.0.0.1:10808, and the new Xray listener failed. The latency test in that thread used a different port, which is why it still displayed a result while browser requests failed. The versions, switching direction and log in that record are checkable; they are not this site's reproduction across macOS versions.

A second record, issue #9863, describes the port still occupied after quitting the client once TUN had been enabled, with commenters reporting it persisted after upgrading. That is why “update to some version” cannot be written as a definite fix. v2rayN's own interface documentation separates TUN settings from system-proxy options and notes that logs can be saved under guiLogs.

Sort by what you observe

ObservationWhat it establishesNext step
The log says failed to listen / address already in use for 10808 or another portThe current core cannot bind that local portRecord port and time; identify the listener
Latency has a value, the browser reports ERR_PROXY_CONNECTION_FAILEDLatency checks and real requests may use different instances or portsDo not judge the node by latency; read the main-core log
lsof shows an old sing-box or Xray listening on that portThe port is genuinely held by that processCheck PID, executable path and whether it belongs to this session
lsof shows nothing, or an unrelated programA single command cannot establish a leftover coreCheck IPv4/IPv6, port number, privileges and configuration; do not kill blindly
No bind error, pages simply failPort conflict is not establishedMove to the general connection checklist

Safe recovery order

  1. Turn TUN off in v2rayN, quit the client, and confirm an ordinary page loads without a proxy. If plain networking is still broken, check for a leftover system proxy or VPN before switching nodes again.
  2. Reopen the log and record the client version, core version, the exact error text, which core was in use before and after the switch, and the local address and port that follow failed to listen. 10808 is only the example from the public case; your log decides.
  3. Identify the listener in Terminal: sudo lsof -nP -iTCP:10808 -sTCP:LISTEN, replacing 10808 with the port from your log. If you use sudo, type the password only on your own machine, and do not paste the full output or the subscription address into a public thread.
  4. Compare the executable path, PID and start time against v2rayN's core directory. If it is a leftover from this session, quit v2rayN normally and wait for it to exit. If it still lingers, terminate only the PID you verified. Do not terminate a listener you cannot identify.
  5. Test with the same node and TUN off, then enable TUN once more. Record four conditions: same node, same target, same port, TUN on or off. If only the sing-box → Xray switch fails, turn TUN off before switching and report a masked log upstream.

If the port is still occupied after the leftover process exits, or the port keeps changing, return to the log and find the earliest failing stage. Changing ports at random, deleting the configuration, reinstalling, or editing DNS at the same time all hide the cause. A failure writing the system proxy belongs to the system-proxy path; the listener error here belongs to v2rayN's local core start.

Ports, processes and what a command proves

CommandWhat it answersWhat it does not answer
lsof -nP -iTCP:PORT -sTCP:LISTENWhich processes hold a listening TCP socket on that port at this momentWhether a process held it a minute ago, or whether a UDP socket is involved
ps -p PID -o pid,lstart,commandWhether the PID's start time matches this client sessionWhether the process is safe to terminate in every case
Main-core log after the switchWhether the new core attempted to bind and what it reportedWhether the node itself is reachable

One lsof result describes one instant. Processes exit, ports change, and a check made after the failure may show nothing at all — which is not evidence that no conflict occurred.

Limits and how to record the case

This page is based on public issue records and interface documentation. This site has not reproduced the experiment on the same macOS build, core versions and node. Do not publish node addresses, subscription tokens, usernames, complete configurations or unmasked logs. Once the port is free, a real page request still has to succeed; releasing a port is not the same as proving the link works.

  • Client and core versions, macOS version and architecture.
  • The exact error line with the local address and port.
  • Which core was used before and after the switch, and the node protocols involved.
  • Whether the latency test and the main core used the same port.
  • What lsof returned, with PID masked if you share it.
  • Whether the problem recurred after a clean quit and relaunch.