v2rayN Core Won’t Start? How to Read Xray Logs and Fix Configuration Errors

1. Tell a Core Startup Failure from a Request Failure

v2rayN is the management interface; Xray is the core that runs the proxy configuration. An open interface doesn’t mean the core is running, and a website timing out doesn’t mean the core failed to start. For a startup failure, check the local configuration and runtime environment. For a request failure, investigate the node, DNS, and remote route.

Don’t rely on the last status message alone. Open the information or log panel in the main window, clear old entries, then restart the active configuration and save the complete sequence from configuration loading through process exit. Log panel names vary by release, so use the labels in your version.

• Startup-stage failure: The log reports a configuration parse error, a resource file that can’t be opened, or a failed bind, then the process exits. Switching nodes usually won’t fix a local error.
• Runtime failure: The core keeps running, but a request triggers a timeout, connection refusal, or handshake failure. First check which outbound handled the request, then verify the server settings.
• The core never ran: The interface says it can’t find the executable or create a process, and there’s no output from Xray. Check the core path, whether the file was quarantined, and execution permissions before changing routing rules.

2. Find the Root Cause in the Log Level and Error Chain

Xray commonly uses the log levels debug, info, warning, error, and none. none disables routine log output, so it’s not useful for troubleshooting. Start with info; if the request path isn’t clear, temporarily switch to debug, then restore the original level to avoid generating excessive connection details.

In v2rayN versions that provide the option, look under Settings → Parameter Settings for log options, save your changes, and restart the active configuration. With custom JSON, check the log section in the file rather than assuming the interface setting overrides it. Configuration parsing errors may also go straight to the process console, so keep the core output from the interface as well.

Error chains often use > to link multiple contexts. The example below shows a typical structure; module prefixes and wording vary by core version. The outer message says loading failed, while the inner messages explain that the configuration couldn’t be read and point to the specific syntax issue.

Failed to start: main: failed to load config files: [config.json]
> infra/conf/serial: failed to read config file
> invalid character '}' looking for beginning of object key string

3. Port Conflicts: Check the Listening Address and Process

A local inbound needs an address and port to bind to. Two processes can’t normally use the same listening endpoint at once. A duplicate core process, another proxy, or even duplicate inbounds in one configuration can cause a conflict. Copy the actual port from the log instead of guessing the default from a guide.

In PowerShell, the commands below check which process is listening on the example TCP port 10808. Check the process name and path before deciding whether to close it; don’t force-terminate a process based on its ID alone.

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

Get-NetTCPConnection -State Listen -LocalPort 10808 |
  ForEach-Object { Get-Process -Id $_.OwningProcess } |
  Select-Object Id, ProcessName, Path

1. If the process is an old Xray instance, exit it normally from its client first. Once it has stopped, start v2rayN again.
2. If another program needs to keep that port, choose a free one in the local inbound settings. If you use a custom configuration, check all inbounds for duplicate bindings.
3. After changing the port, check that your browser’s manual proxy settings and the system proxy no longer point to the old port. If the core starts but an app still connects to the old port, you’ll get a different connection error.
4. If the error says forbidden by its access permissions, don’t assume the port is occupied. Check the system’s reserved ranges with netsh interface ipv4 show excludedportrange protocol=tcp, then investigate security policies.

4. JSON Syntax Errors: Test the File Used at Startup

Saving changes in the node editor doesn’t guarantee that custom snippets form valid configuration. Common problems include a trailing comma, curly quotation marks copied from a document, a missing closing quote, or unescaped backslashes in Windows paths. Use forward slashes in paths, or write each backslash as \\ in a JSON string.

Open PowerShell in the directory containing the Xray executable. Name a copy of the configuration actually used for this run config.json, then run the command below. If the file is elsewhere, use its real full path. Testing an old backup won’t verify the startup configuration v2rayN just generated.

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

run -test checks whether the current core can load the configuration; it doesn’t replace testing normal port binding or remote connectivity. Use the same resource directory and environment variables as the client, or a manual test may fail to find geo files even though the client can. Auto-generated files may be overwritten at the next startup, so make the lasting change in the node editor, routing settings, or custom configuration source file.

5. Missing Geo Files: Check File Paths and Rule Categories

geoip:private and geosite:cn aren’t plain text that gets expanded automatically. When Xray loads these rules, it needs to read the corresponding data files. Missing files, an incorrect working directory, an overridden resource path, or a nonexistent category can all prevent configuration from loading. Copying only the JSON to another directory often leaves these dependencies behind.

• Find the path being accessed first: Use the actual path in the log. A file with the same name in your downloads folder doesn’t prove the dependency is in place.
• Then check the resource settings: In a custom runtime environment, XRAY_LOCATION_ASSET affects where resources are found. Verify that it points to the intended directory.
• Distinguish missing files from missing categories: “File not found” and “category not found in file” are different issues. For the latter, change the category name or use a data source that includes it. Re-copying the same file won’t help.
• Restore only what’s needed: Use the client’s resource update feature to restore the files it uses. If you temporarily remove a rule to isolate the issue, save a copy first and restore your original routing behavior after testing.

6. Field Names and Nesting: Valid JSON Can Still Be Misconfigured

Valid JSON only means its braces, quotes, and other syntax can be parsed. It doesn’t guarantee that fields are in the right place, have valid values, or match the core’s capabilities. Check which core’s configuration format a copied snippet uses. v2rayN’s interface settings and Xray’s native JSON are different formats; you can’t give the interface settings file directly to Xray to run.

For example, domainStrategy belongs under routing, not inside an individual rule in rules. This is only a routing snippet. It assumes the full configuration defines a direct outbound named direct and that the required geo data is available; it isn’t a complete, runnable configuration.

{
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "domain": ["geosite:cn"],
        "outboundTag": "direct"
      }
    ]
  }
}

• Check capitalization: outboundTag isn’t interchangeable with a field name that’s been arbitrarily changed. The outbound tag value must also match its definition.
• Check data types: rules must be an array. Use domain and ip in rules as specified for those fields; don’t paste rule text from other software directly into JSON.
• Check core version support: Record the actual output of xray.exe version, then confirm the core supports the transport and security fields you’re using. Don’t infer the core version from the client window title.
• Check the result: Some unknown fields may be ignored rather than triggering an error. After the configuration test passes, use runtime logs and request results to confirm that the rules actually took effect.

7. Verify the Fix and Answers to Common Questions

Change one clearly identified issue at a time, then restart and save the new log. Don’t upgrade the core, change ports, edit routing, and switch nodes all at once; even if the connection comes back, you won’t know which change fixed it. Once everything works, restore the original log level and save a working configuration copy.

1. Configuration check: The current core tests the actual configuration without errors reading it, parsing fields, or loading resources.
2. Process check: After a normal startup, the process stays running and the expected local port is listening instead of the core exiting immediately.
3. Request check: Configure an app to use the new port to reach a destination. Check the logs to confirm the request reaches the core, then look for any new remote connection errors.
4. Persistence check: Close and reopen v2rayN to make sure the fix wasn’t overwritten by an auto-generated configuration.