At a glance

Use this guide when Xray won't start after you select a node in v2rayN, keeps exiting, or reports a configuration error in the logs. Save the first failure log, then check the listening port, configuration fields, node transport settings, and Core capabilities one by one. Don't confuse a Core that starts successfully with a node that can't connect.

Start by finding where the failure occurs in the logs

v2rayN manages nodes and generates the runtime configuration. The Xray Core reads that configuration, opens local listeners, and handles connections. When startup fails, the tray icon or a browser error shows the outcome but rarely the cause. Open the Log section in the v2rayN main window and restart the service once. Find the first error logged after that action. The log menu may have a slightly different name in other versions; focus on Core output, not subscription update entries.

When reading the log, first identify which of three stages failed: a configuration parsing error usually mentions a field or JSON syntax; a local listener error often includes listen, bind, and a port; a failure to connect to a remote host after the Core starts may mention DNS resolution, a handshake, or a timeout. The final “startup failed” line is often just a summary—the useful clue is usually above it.

  1. Note what happened

    Record whether the failure occurred after selecting a node, switching the system proxy, or changing a setting. If it worked before, check the settings you changed most recently first.

  2. Restart the service

    Open Log in the main window and select Restart Service once. If your version uses a different menu label, use its equivalent Core restart option. Focus only on errors added by this attempt.

  3. Find the first error

    Starting at the top of the new log entries, find the first line containing error, failed, or bind. Note the port or configuration field it mentions.

  4. Keep a record

    Before making changes, copy the relevant error and a summary of the current node settings. Before asking for help, redact server credentials, subscription URLs, and personal network details.

Local port conflicts: check the listening address and port

At startup, the Core must bind to a local proxy port. For example, SOCKS might use 127.0.0.1:10808 and HTTP 127.0.0.1:10809. These are examples only; check the local port settings under v2rayN Settings → Parameter Settings and the current log for the actual values. If another process already uses the same address and port, the new Core can't open its listener.

10808
Example SOCKS local port—not a fixed value
10809
Example HTTP local port—not a fixed value

Error: bind: address already in use

Cause and fix: Another process is already using the listening address and port. Close any duplicate client instance first. If the conflict persists, identify the process using the port, then change the local port and restart the service.

Error: bind: Only one usage of each socket address (protocol/network address/port) is normally permitted.

Cause and fix: The system is reporting a socket binding conflict. Check the listen tcp address earlier in the same log entry and investigate that port. Don't assume it's the default port.

In a Windows terminal, run netstat -ano | findstr :10808 to find the process ID using the example port, then look up the process in Task Manager. On macOS or Linux, run lsof -nP -iTCP:10808 -sTCP:LISTEN to see which process is listening. Replace 10808 with the port shown in your log. Once you've identified the process, close the duplicate instance or change v2rayN's local listening port. Don't terminate an unfamiliar system process.

Check the listening address in the log

The scope of a conflict can vary when the same port is bound to different addresses. Check the full address and port in the log before deciding what to change. Switching remote nodes usually won't free a local port.

Configuration fields and JSON syntax: find the first parsing error

After you edit a custom configuration, import a config snippet, or change an advanced option, the Core may exit before opening any connection. Xray reads the generated runtime configuration, where an extra comma, mismatched bracket, or misplaced field can make the entire file unreadable. Distinguish an error in the original node details from a problem parsing the generated configuration.

Error: invalid character '}' looking for beginning of object key string

Cause and fix: The JSON object expected a field name but encountered a closing brace. Check for an extra comma, a missing field name, or mismatched braces nearby. Fix the configuration, regenerate it, and start the Core again.

Error: invalid character ',' looking for beginning of value

Cause and fix: A field may be missing a value after its colon, or an array may contain an extra separator. Check the fields around the reported location, not just the character named in the error.

In v2rayN, first roll back the custom configuration you just changed, then restore settings one at a time. If the error comes from a subscription node, inspect that node's editing screen and refresh the subscription if needed. A subscription update may overwrite manual edits, so note the node's protocol, server address, port, transport, and TLS settings before troubleshooting. Don't mix protocol fields for VMess, VLESS, or other protocols, or copy fields into another protocol's configuration just because their names look similar.

If the log names a field or location, use the runtime configuration as your reference. A JSON syntax error can usually be reproduced at startup; an unresolvable server address or a refused remote connection is a later connection-stage problem. Fix the syntax and confirm the Core stays running before troubleshooting connectivity, so you don't conflate the two types of error.

Change one thing at a time

Once you have a configuration that starts, add back one field or related group of options at a time, restarting the Core after each change. This makes it easier to identify which change introduced the parsing error.

Transport mismatches: check each setting against the node details

A protocol name alone doesn't tell you everything needed to connect. For a VLESS node, for example, check the transport, server port, security settings, and parameters required by that transport. WebSocket paths and Host values, gRPC service names, and TLS server names each serve a different purpose and aren't interchangeable. In v2rayN, right-click the node and choose the server editing option to compare each setting with the original details from your provider. Menu labels vary by client version.

A transport mismatch doesn't always cause the Core to fail at startup. If the log shows that the local port is listening, followed by a handshake failure or closed connection, focus on the node's remote settings rather than the local port. Test the same Core with another known-good node: if that works and only one node fails, check that node's settings first.

Error: failed to find an available destination

Cause and fix: This error means the connection couldn't find an available destination. Check the preceding DNS or connection entries, then verify the server address and remote port. On its own, this error doesn't prove that the Core failed to start.

If every node fails at the same point, check shared settings, the selected Core, and your local network. If only one node fails, avoid changing global routing, DNS, and the system proxy all at once. Test one node and one setting at a time so you can compare the logs.

Core version differences: check the selected Core and supported settings

v2rayN is a management interface; Xray is one of the Cores it can run. Being able to save a setting in the interface doesn't mean the Core currently in use can recognize it. After updating the client, switching Cores, or importing a newer node configuration, a previously working service may report an unrecognized protocol or setting at startup. Check the selected Core and its version before changing the server address.

  1. Confirm the Core

    In v2rayN, open Settings → Parameter Settings and look for Core Type or the equivalent option in your version. Confirm that Xray is handling the node.

  2. Check the version

    Find the Xray version in v2rayN's Core management screen or startup log. Don't confuse the v2rayN client version with the Core version.

  3. Check the settings

    Check the protocol, transport, and security settings in the imported configuration, and confirm that the current Core supports them. If you recently updated the Core, make sure your custom configuration is still compatible.

  4. Test one node

    Restart the service with a clearly specified node. Once the Core stays running, restore other nodes and custom rules gradually.

Don't assume that a newer version is always the answer. If the log reports a port conflict, changing the Core version won't free the port. If it reports a JSON syntax error, fix the configuration first. Prioritize a version issue only when the error points to an unsupported setting and the behavior changed after switching or updating the Core. For client or Core installation steps, see the client download page and getting started guide.

Verify the fix and get answers to common questions

After making a fix, check two things separately: whether the Core started successfully and whether the target connection works. Look for the same startup error in the new log and confirm that the local listening port is open. Then test the selected node and the apps that need the proxy. The system proxy setting only affects apps configured to use it; a command-line connection failure alone doesn't mean the Core failed to start.

The log only says “startup failed.” Where should I look?

In Log, restart the service once and look upward for the earliest detailed error from that attempt. Note any field, address, or port mentioned, then troubleshoot the corresponding category.

I changed the local port. Why does the conflict persist?

Check which port the latest log actually tried to bind, and see whether another listener—such as SOCKS or HTTP—is still using a conflicting port. Restart the service after changing it, then check which process owns the port.

It works after switching nodes. Does that mean the Core is fixed?

Check whether the Core had already opened a local listener when the old node failed. If it had, switching nodes addressed a node configuration or remote connection problem, not a Core startup issue.

The error came back after I updated the subscription. Why?

A subscription update may restore the node's original settings. Compare the transport, security, and server fields before and after the update to determine whether the issue is in the subscription or your local custom configuration.

Do I need to reset all settings?

Usually not. Save the relevant logs and roll back the most recent change first. Only if you can't isolate the difference should you back up your settings and reproduce the issue with a minimal configuration.

Keep a copy of the error from before the change and the startup log from after it. If the first error is gone and the listener is open but websites still won't load, check the system proxy, DNS, routing rules, or remote node. Troubleshooting by stage helps prevent separate issues from getting lumped together as “Core startup failed.”