V2Ray Core Won’t Start? Read Logs to Find Config Errors

1. First, Check Whether the Core Failed to Start or Requests Can’t Connect

v2rayN provides the client interface; cores such as Xray and V2Fly read the config, set up inbound listeners, and make outbound connections. Being able to open the interface or update subscriptions doesn’t mean the core is running. Likewise, a webpage failing to load doesn’t necessarily mean the core failed to start: remote timeouts, certificate verification errors, and DNS lookup failures can all occur after startup.

This sequence helps identify the stage where an error occurs; it isn’t a precise account of the internal call order for every core version. Start with the most specific cause in the startup failure log. If the core is still running and you then see connection refused or i/o timeout, check the destination to determine whether the issue is local or remote. Don’t assume it’s a JSON error.

• Config stage: Parse errors, unrecognized protocols, or failures to read rule data usually mean you need to fix the config or resource path first.
• Listener stage: If the log contains terms such as bind or listen tcp, check the local address, port conflicts, and permissions first.
• Request stage: If inbound traffic is being received before a remote timeout occurs, check the node, DNS, routing, and server connectivity.

2. Capture a Complete Startup Log

Capture the log from before you click Start through the point where the error appears. Don’t just screenshot “startup failed”—that message is usually only the outcome. The actual cause is often in a following failed to message, filename, or system error. Repeated startup attempts can mix logs from multiple runs, so stop the service and reproduce the issue once.

1. Record your environment

   Note your operating system, client version, and the core name and version currently in use. v2rayNG uses Xray; v2flyNG uses V2Fly. In v2rayN, check which core is selected rather than inferring it from the window title.

2. Open the logs

   In v2rayN, check the log area at the bottom of the main window. Expand the log panel if it’s collapsed. In v2rayNG, open “Logs” from the main menu. Menu locations may vary by version, so follow the labels in your current interface.

3. Reproduce once

   Stop the connection, note the current time, and start it once. Keep the continuous log from before and after startup. Save the first failure message and its full cause chain, not just the last line.

4. Back up before editing

   Back up custom configs and routing rules, and change one variable at a time. Before sharing logs, redact subscription URLs, node credentials, UUIDs, server addresses, and personal directory names. Keep field names, error types, and ports visible.

If the client says it can’t create a core process and there’s no core output at all, first check whether the core executable exists, the archive was fully extracted, the system’s security logs show it was blocked, and the package matches your processor architecture. This happens before config parsing, so repeatedly changing node settings usually won’t help.

3. Port Already in Use: Find the Listening Process Before Changing Ports

A local proxy must bind to a listening address and port. Two independent listeners usually can’t use the same TCP port on the same address at the same time. A duplicate client instance, a leftover core process, or another application using the same port can make the new core exit immediately. Don’t confuse the remote server port with the local inbound port.

These values are examples for troubleshooting, not defaults for every version. If the log shows a bind failure on 127.0.0.1:10808, run the command below in Windows PowerShell to find the process ID using the port, then look up the process name.

Get-NetTCPConnection -State Listen -LocalPort 10808 |
  Select-Object LocalAddress, LocalPort, OwningProcess

Get-Process -Id (Get-NetTCPConnection -State Listen -LocalPort 10808).OwningProcess

On Linux, run ss -ltnp 'sport = :10808'; on macOS, run lsof -nP -iTCP:10808 -sTCP:LISTEN. No results only mean there was no matching TCP listener at the time of the query. It doesn’t rule out a startup-time conflict, a UDP conflict, or a permissions issue; check the network type in the log.

• If you find an old core process, exit it normally from its client, make sure the port is free, and then start the client you want to use.
• Before switching to 10818, check that it’s free too. After changing the port, update any manually configured browser or terminal proxy settings and other local access settings.
• If the log points to a local IP address that doesn’t exist, correct the listening address. For local access only, use 127.0.0.1 if appropriate. Don’t expose the service on every network interface just to clear the error.

4. JSON Errors: Distinguish Invalid Syntax from Incompatible Fields

Strict JSON requires English double quotes around keys and strings, and commas must be placed correctly between arrays and objects. Curly quotes, a trailing comma, or a missing bracket after copying can all cause a read-time failure. Some config loaders support extensions such as comments, but others may not. To avoid compatibility issues, use strict JSON in your troubleshooting copy.

The snippet below illustrates JSON syntax; it isn’t a complete proxy config you can run as-is. There’s no trailing comma after loglevel, and both the outer and inner objects are closed:

{
  "log": {
    "loglevel": "warning"
  }
}

Passing a JSON syntax check only proves that the text is valid JSON. It doesn’t confirm that the protocol name, transport settings, or field types are correct. Some unrecognized fields may also be ignored rather than causing startup errors. Continue by testing the config with the core you actually use.

.\xray.exe run -test -config .\config.json

• The example applies to Xray versions that provide this command. Run .\xray.exe help run first to check the options. On Linux and macOS, use the path to the corresponding executable.
• config.json must be a local copy of the actual config. If the client generates the config automatically, make sure you’re testing the same content the current node uses at runtime.
• Command-line tests and client startup may use different working directories, environment variables, and resource paths. Even if the test passes, check the config again in the client.
• Don’t upload a complete JSON file containing node credentials to an unfamiliar online formatter. Use a local editor and the core’s config test feature instead.

5. Unknown Protocols and Fields: Check Which Core Is Running

Share links, subscription content, and native configs are different types of input. A vless:// or vmess:// share link must be parsed by the client; you can’t save it directly as a JSON config for the core to read. A node appearing in your subscription list also doesn’t mean the current core supports all its transport and security settings.

VLESS is a protocol name; REALITY is part of the related security configuration. They aren’t interchangeable as the value of protocol. The transport, security settings, server name, and credentials must match the server requirements. Changing the protocol name to one that starts successfully doesn’t mean the node will connect.

• v2rayN: Check which core the current node uses and review its startup log. After switching cores, regenerate the config so you don’t keep testing a file left over from a previous run.
• v2rayNG: Check the Xray features included with the client. If a new parameter isn’t recognized, confirm the client and core versions before deciding whether to update.
• v2flyNG: Follow the V2Fly config specification. Don’t assume a complete JSON config written for Xray can be imported unchanged and behave the same way.

6. Missing Geo Files: Check Data Names, Paths, and Rule References

Routing references such as geosite: and geoip: depend on the corresponding data. Even with valid config syntax, rule building can fail if the runtime can’t find the data files or the data doesn’t contain the referenced category. First check whether the error says the file can’t be opened or the category can’t be found; the fixes are different.

1. Note the filename in the error, such as geosite.dat or geoip.dat, along with the full path. Don’t guess where resources are stored based only on the client’s install directory.
2. Make sure the file is readable and isn’t empty. Linux filenames are case-sensitive, and directory permissions can also prevent the core from reading a file.
3. Restore the compatible data files using the client’s data update option. If there’s no such option in the interface, follow the client’s resource management method. Don’t mix data files in different formats.
4. If the file exists but the log says the category wasn’t found, check the spelling after geosite: and confirm the category is present in the current data. Not every data file includes third-party categories.
5. Back up your config, temporarily remove the single problematic rule, and try starting again. If startup succeeds, you’ve narrowed the issue to that rule or resource. Restore the complete data and rule before using the final config.

Removing all routing rules during troubleshooting changes where requests go: traffic meant to connect directly may be sent through the proxy, or proxy traffic may go direct. Once you’ve identified the issue, restore your original routing intent and check that outboundTag matches an existing outbound tag.

7. Android Service Issues and Post-Fix Checks

On Android, v2rayNG uses the system VPN interface to handle traffic. A VPN authorization failure and an Xray config parse failure are different issues: for the former, check system permissions, other VPN services, and device policies; for the latter, use the logs to investigate JSON, protocol, or resource errors. v2flyNG uses the V2Fly core, but the same distinction applies.

• Service stops immediately after starting: Check the first error in the startup log, then confirm system VPN permission was granted. Don’t rely on the status bar icon alone to identify the cause.
• Another VPN is running: Stop the conflicting VPN service first. Android usually allows only one active VPN service per user to handle traffic.
• Disconnects only after the screen locks: If startup works but the service stops after running in the background for a while, check battery optimization and background restrictions. This isn’t a typical config read failure.
• Service runs, but no traffic flows: Check the app proxy scope, DNS, routing, and whether the current node is reachable. The system VPN interface being active doesn’t mean every app’s requests are reaching the intended outbound.

After making a fix, retest with the same node and under the same conditions. First make sure the core stays running, then confirm the local listener or Android VPN service is working, and only then test webpage access. System proxy settings, VPN access, and the core process are separate stages; any one working on its own doesn’t prove the whole connection is working.

1. Restart and verify

   Stop the service and start it again. Confirm the original error is gone. If a different error appears, continue troubleshooting at the stage it relates to.

2. Check the connection

   On desktop, check the actual listening port and system proxy settings. On Android, check the VPN service and app scope. If the port changed, update all manually configured connection settings.

3. Make a request

   Visit a known-working HTTPS page in your browser and watch the log for the corresponding request. If the only error is a remote timeout, investigate the node and network instead of repeatedly changing JSON punctuation.

4. Restore your settings

   Restore any routing and log-level settings you temporarily changed during troubleshooting, then save a copy of the final config. Record the original error, what you changed, and the verification result so you can compare after future updates.