V2Ray Core Won’t Start: Find config.json Errors in the Logs

1. Core Startup Failure or Connection Failure? Identify the Stage First

An open client window doesn’t mean the core is running. v2rayN is a management interface; the core process it launches handles inbound connections, routing, and outbound connections. At startup, the core typically reads the configuration, builds protocol and routing objects, then opens local listeners. If any step fails, there’s no entry point for proxy requests.

If Failed to start appears immediately after launch, look further down for a more specific cause. If the logs confirm that a listener started successfully, but requests time out or fail authentication or the TLS handshake, the issue is usually at the connection stage. Changing JSON commas won’t help, and the client’s “connection failed” message alone doesn’t prove the core failed to start.

• Parsing: Look for messages such as invalid character or unexpected EOF, then check the file contents first.
• Configuration build: Check protocol names, transport settings, routing tags, and resource file paths.
• Listening: Look for bind, address already in use, and permission-related messages.
• Connection: Once the core is running, check the server address, DNS, system time, and server-side settings.

2. Get the Full Logs and Confirm Which Configuration Is Loaded

Don’t capture only the final “process exited” line. The actual cause is often at the end of the same error chain, joined by separators such as >, or appears before the exit message. Keep the complete log for this startup, from the core version and launch command through the exit reason, so you don’t mix an earlier connection error with the current startup failure.

1. Save the Details

   Copy the current startup log from the log panel and back up your active custom configuration. Before sharing logs, remove sensitive information such as subscription URLs, user IDs, passwords, private keys, and server addresses. Keep the original file unchanged on your device.

2. Confirm the Core

   Check the startup log for the executable name, version, and configuration path. v2rayNG uses the Xray core, while v2flyNG uses the V2Fly core. For v2rayN, rely on the current startup log rather than inferring the core from the client name.

3. Check the Settings

   In desktop v2rayN, check local listener settings under “Settings” → “Parameter Settings.” The names of subpages may vary between versions, so follow the interface you actually see. Compare the ports shown in the interface with inbounds in the generated configuration.

4. Test Separately

   Stop the client’s proxy service first to prevent interference from duplicate processes. Run the configuration test for the relevant core against the file identified in the logs. Don’t substitute a same-named config.json from another directory.

These are common command formats to run from the core’s directory. The first applies to Xray on Windows; the second applies to V2Fly builds that provide the test subcommand. Older versions may use different arguments, so check with that binary’s help or -h first. Enclose filenames containing spaces in quotes.

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

./v2ray test -c ./config.json

3. JSON Syntax Errors: Find the Character, Then Check the Fields

JSON parsing happens before protocol validation. Even with the correct node address and port, the core cannot read the configuration if parsing fails. Check the quotes, commas, braces, and brackets near the reported character. The reported position is where the parser stopped; the missing comma may be on the previous line.

Here’s a strict JSON inbound snippet. It demonstrates strings, numbers, and bracket structure only; it isn’t a complete configuration and cannot replace the original file. JSON uses straight double quotes. Curly quotes won’t work for keys, and backslashes in Windows paths must be escaped.

{
  "inbounds": [
    {
      "tag": "local-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "udp": true
      }
    }
  ]
}

• Strict JSON does not allow trailing commas. To avoid differences between parsers, use standard JSON without comments while troubleshooting.
• Use a number in "port": 10808; don’t turn every number into a string by default.
• A path can be written as "C:\\proxy\\access.log", provided the directory exists and the process can write to it.
• Inspect sensitive configurations with a local editor; don’t upload them to an online formatter.

4. Port Conflicts: Identify the Process Instead of Restarting Repeatedly

Passing a configuration test doesn’t guarantee that the core can bind its ports at runtime. Conflicts can occur if an old core process is still running, two client instances launch at once, or HTTP and SOCKS inbounds use the same listening address and TCP port. On Windows, the error may read Only one usage of each socket address; other systems commonly report address already in use.

These numbers are examples, not defaults for every version. Check the actual ports under “Settings” → “Parameter Settings” before running the commands. In Windows PowerShell, you can check which processes are listening on the two example ports below. If the query returns nothing, it only means no matching TCP listener was found at that moment; it doesn’t rule out permission or address configuration issues.

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

# Set -Id to the process ID found in the previous step; 4560 is only an example
Get-Process -Id 4560

On Linux, use the command below to inspect listening addresses, ports, and processes. You may need additional permissions to view other users’ processes. Also check for processes listening on 0.0.0.0 or ::, as they may conflict with a new listener on a local address.

ss -ltnp 'sport = :10808 or sport = :10809'

• If it’s an old core process: stop the service normally from the corresponding client, confirm the process has exited, and then start it again.
• If it belongs to another application: don’t terminate an unfamiliar process. Choose an available port for the proxy and update the system proxy or application proxy settings to match.
• If permission denied persists after changing the port, check system policies and reserved ports. Disabling the firewall is not a general-purpose fix.
• If the core never started listening successfully, changing browser proxy settings, DNS, or the remote node usually won’t fix a local binding error.

5. Unknown Protocols and Fields: Check Core Compatibility

Valid JSON only means the file can be parsed; it doesn’t mean the field combinations are valid. Xray and V2Fly share a common origin, but their protocols, transports, and security settings aren’t interchangeable across the board. Configurations using REALITY or Xray-specific flow-control settings require a core and version that explicitly support them.

Not every unknown field produces an error; some parsing paths ignore unrecognized keys. So the absence of an “unknown field” message doesn’t prove that a setting took effect. Client options such as subscription groups and automatic update intervals also don’t belong in the core’s JSON. Manage them in the client’s settings instead.

6. Missing Geo Files: Check the Name, Path, and Permissions

Routing rules using geoip: and geosite: generally require the corresponding geo data files. If the logs show failed to load GeoIP or failed to load geosite, read the rest of the error chain: a missing file, a read failure, and an unknown category are three different issues.

• Check the filenames: Common names include geoip.dat and geosite.dat. Make sure the extension isn’t hidden and added twice.
• Check the resource directory: Where resources are searched for depends on how the client starts the core, the core itself, and environment settings. Don’t assume it’s always the terminal’s current directory.
• Check the category: If the file exists but the requested rule category doesn’t, update the matching data set or correct the category name in the rule. Recopying the same file won’t help.
• Check the update: A failed update may leave an empty or invalid file. Fetch a compatible resource through the client and test again; simply renaming the file won’t fix it.

To narrow down the issue, temporarily remove the geo-related routing rules from a backed-up copy, then test the configuration. If the copy passes, the problem is limited to the resources or rules. Before using the configuration, fix the original rules; otherwise, traffic routing will change.

7. Retest After Fixing: Separate a Valid Configuration from a Working Proxy

Change one variable at a time and record the error lines before and after each change. Once the configuration test passes, start the core and confirm that it’s listening. Then check whether application requests reach the inbound and whether routing selects the expected outbound. Successfully opening one webpage doesn’t prove that every routing rule is correct.

When reporting an issue, include the client name, actual core version, operating system, the complete startup error chain with sensitive details removed, and the smallest configuration snippet that reproduces the problem. For basic setup, see the Quick Start Guide. For inbound, outbound, and routing fields, see the Complete Configuration Guide.