Use this guide if v2rayN reports that the core failed to start after switching servers, exits as soon as you import a custom config, or can’t load routing rules after a core update. Start by using the logs to tell whether the config failed to load, a local listener couldn’t start, or the core started but connections are failing. Then check ports, JSON syntax, field compatibility, and geo data. Finally, test the config and a real request separately so you don’t mistake a failed subscription fetch for a core issue.
1. Core startup failures vs. connection failures
v2rayN is the management interface; Xray or V2Fly is the core process that runs the proxy config. The main window opening and the server list appearing don’t mean the core is running. Startup failures usually happen while the core reads the config, builds inbounds and outbounds, or binds a local port. Node timeouts, certificate mismatches, and remote connection refusals can happen after the core has started.
First, pinpoint when the failure occurs. If a config parsing error appears immediately after you set an active server, start with the local config. If startup looks normal and errors appear only when you open a webpage, check the server address, network, TLS, and transport settings. Changing the local listening port over and over won’t usually help.
| Log message or symptom | Stage | Check first |
|---|---|---|
failed to load config | Reading or building the config | Look further down for JSON, protocol field, or data file errors |
failed to listen TCP | Starting a local listener | Listening address, port conflicts, and system-reserved ports |
connection refused | Connecting to a destination | Check whether the address in the error is the local inbound or remote server |
context deadline exceeded | Operation timed out | Use the context above to determine whether the timeout occurred during DNS lookup, connection, or handshake |
2. Identify the core and config file from the logs
Record the core and config actually used for this launch—not just a file that happens to be in the program directory. v2rayN typically generates a runtime config based on the active server and routing settings. Changes made directly to a generated file may be overwritten when you switch servers. For persistent changes, use the relevant parameter settings, routing settings, or custom config source.
-
Preserve the evidence
Copy the error from this launch in the log area at the bottom of the main window, and note whether you started the core, switched servers, or changed routing. Back up custom configs before editing so you don’t overwrite your only reproducible example.
-
Confirm the core
Open “Settings” → “Parameter Settings” and check the options for “Core type.” Compare them with the Xray or V2Ray version shown in the startup log. Labels and sections can vary by version; the process shown in the log is the definitive source.
-
Locate the file
Use the startup information or error path to identify the config file being read. If the interface doesn’t show the full path, check the client logs and runtime directory. Don’t guess based on the filename or treat a subscription response as a runtime config.
-
Retry one change at a time
Change one thing at a time, restart the core, and save the new error. If the previous error disappears and a new one appears, you’ve made progress—there’s no need to revert every setting and start over.
If the logs show no config parsing and instead report that the executable is missing, the process can’t be created, or access is denied, first check that the core files are present, the program directory is readable and writable, and security software hasn’t blocked the process. These failures happen before the config reaches the core, so editing JSON won’t help.
3. Port conflicts: find the PID before changing the local listener
The numbers below are examples for troubleshooting, not defaults for every version. Check the local listening ports under “Settings” → “Parameter Settings” and replace the numbers in the commands as needed. Some versions use a mixed inbound port, so don’t assume SOCKS and HTTP must always use separate ports.
Error: bind: address already in use
Cause: Another process is using that listening address and port. A core left running by another v2rayN instance may also be the cause.
Fix: Identify the process using the port and close any duplicate instance normally. If both programs need to run, assign different local ports to one of them.
Error: Only one usage of each socket address
Cause: This is a common fragment in Windows port binding errors. The full message also includes the listening address and port.
Fix: Find the PID for the exact port shown in the log. Don’t terminate every core process just because you see a binding error.
Find the listening process on Windows
netstat -ano -p tcp | findstr ":10808"
netstat -ano -p tcp | findstr ":10809"Treat a port as in use only if the matching local address is in a row with status LISTENING. The command may also match remote addresses, so a matching number alone doesn’t prove a conflict. The rightmost column is the PID; look it up under “Details” in Task Manager. You can also use this PowerShell command to see the process name:
Get-NetTCPConnection -LocalPort 10808 -State Listen |
Select-Object LocalAddress, LocalPort, OwningProcess,
@{Name='ProcessName';Expression={(Get-Process -Id $_.OwningProcess).ProcessName}}Key point: update apps that connect to the local port
If you change the local port from 10808 to another value, update it in browsers, terminals, and apps where you set the proxy manually. If you use the v2rayN system proxy, reapply “Set system proxy automatically.” Restoring the core listener doesn’t automatically point apps to the new port.
If the error mentions access permissions, such as forbidden by its access permissions, and no listening process appears in your query, check the system’s excluded port ranges with netsh interface ipv4 show excludedportrange protocol=tcp. Choose a port that isn’t in use or reserved; don’t delete system-reserved ranges.
4. JSON syntax errors: fix punctuation and structure
Standard JSON requires English double quotes around object keys and strings. It doesn’t allow trailing commas or curly quotes as delimiters. Some loaders may support comments or other extensions, but standard JSON is easier to validate across tools. Passing a syntax check only confirms the text is well-formed; it doesn’t prove that protocol or routing fields are valid.
Error: invalid character '}' looking for beginning of object key string
Cause: A common cause is a trailing comma after the last item in an object. The parser expects another key but finds the closing brace.
Fix: Check the location reported and the item immediately before it. Remove any trailing comma and make sure all brackets and braces are paired.
Error: unexpected EOF
Cause: The content ends before the structure is complete, often because the config was copied incompletely, a string wasn’t closed, or a closing bracket is missing.
Fix: Restore the missing content from the complete source file. Don’t blindly append closing brackets to the end of the file.
This valid JSON logging snippet illustrates nesting and comma placement. It isn’t a complete proxy config and can’t replace the runtime config on its own.
{
"log": {
"loglevel": "warning"
}
}- Check the quotes:
"loglevel"is a valid key; curly quotes aren’t. - Check commas: members at the same level need commas between them, but the last member doesn’t need one.
- Check the path: escape backslashes in Windows paths inside JSON strings, for example
"C:\\proxy\\error.log". - Check the file contents: if it starts with an HTML tag, you may have saved an error page. A string of subscription-encoded data isn’t native runtime JSON either.
Don’t upload configs containing credentials to online formatters. Check punctuation in a local editor, then validate the config’s semantics with the test command for the same core. If the same issue keeps appearing in files generated by v2rayN, check the custom config or template source instead of repeatedly editing the generated output.
5. Unknown fields and core differences: check protocol, type, and nesting
Xray and V2Fly share some config basics, but parameters for newer transports, security options, or protocols in one core can’t necessarily be copied straight into the other. Even when both configs are JSON, a field may not be recognized by a different core version. VLESS and VMess are protocol names, not general-purpose config formats. A client importing a share link doesn’t mean every core version supports all its parameters.
| Log clue | Possible cause | What to do |
|---|---|---|
unknown field | The loader checks fields strictly, or a field is at the wrong nesting level | Check the field definition and nesting for the relevant core version |
unknown config id | The protocol or transport type isn’t supported, or its name is misspelled | Check the type named in the error and the core in use. Don’t copy configs between cores without checking compatibility |
cannot unmarshal | A string, number, array, or object has the wrong type | Use the full error to locate the field. Don’t just change quotes to make the parser accept it |
| No error, but the setting has no effect | The unknown field may be ignored, or you may be editing a file that isn’t used at runtime | Check the generated config and actual behavior; a successful test exit alone isn’t enough |
Not every unknown field causes startup to fail; behavior depends on the core version and how the config is loaded. So, the absence of unknown field doesn’t prove that a field took effect. Prefer the structured editor in v2rayN. If you need custom JSON, check the actual core’s help output, config hierarchy, and version support.
6. Missing geo files: check the file, path, and collection name
In routing rules, geosite:cn refers to a domain collection, while geoip:cn refers to an IP collection. With the common DAT data format, these depend on geosite.dat and geoip.dat, respectively. The core must be able to find the data file and the referenced collection within it. A file existing, being readable, and containing the collection are three separate requirements.
Error: failed to load geosite
Cause: A domain rule failed to load. The following errors may point to a missing file, unreadable content, or a collection that doesn’t exist.
Fix: Read the full error chain. First confirm the active data directory, then check the file and the referenced collection separately. The filename alone isn’t enough.
Error: no such file or directory
Cause: If the preceding lines point to a geo data path, the core couldn’t find the required file there. On Windows, the message may instead say “The system cannot find the file specified.”
Fix: Restore the data file at the full path shown in the error, or correct the resource directory. A file with the same name elsewhere doesn’t prove the issue is fixed.
- Missing file: Use the client’s data file update option to download it again. Menu locations vary by version; verify the update and the actual resource path.
- Corrupt file: If the core reports a read or parsing error, download the complete data file again. Don’t rename a downloaded error page to
.dat. - Collection not found: Check the name after
geosite:orgeoip:. Different data sources don’t necessarily include the same collections. - External data reference: For
ext:filename:collection, check the custom filename, resource directory, and collection. Updating only the default file won’t help.
For a temporary test, disable the geo rule you added that triggers the error, then regenerate the config and start the core again. This can show that the rule or its data dependency is involved, but it isn’t a permanent fix. Removing a routing rule can change where traffic goes. After restoring it, test destinations that should connect directly, through the proxy, or be blocked.
7. Test the config and real requests separately
Test the config with the core version v2rayN actually calls and the same data resources. Otherwise, a manual test may fail to find geo files because the working directory differs, or produce a different result because it uses another core. The example below is for Windows and assumes the current directory contains the core executable and the config.json to check. Use the actual path if the file is elsewhere.
.\xray.exe version
.\xray.exe run -test -config .\config.jsonV2Fly command-line syntax varies by major version. Versions that use subcommands can use the command below. If you see an unknown command error, check the current executable’s help instead of copying startup arguments from another version.
.\v2ray.exe version
.\v2ray.exe help
.\v2ray.exe test -c .\config.jsonA config test usually checks only whether the config can be loaded and built. It doesn’t start a complete runtime listener or make a real remote connection. Passing the test therefore doesn’t rule out port conflicts, an unreachable server, or a failed handshake. After fixing the issue, start the core in v2rayN and verify the following in order.
- Check startup: Confirm the same launch no longer reports config parsing, data loading, or listener errors.
- Check the listener: Use a port query to confirm the expected port is listening and belongs to the core you just started.
- Check the proxy setup: Verify the system proxy or the proxy address set manually in the app. The system proxy being enabled and the core starting successfully are separate things.
- Check a real request: Make an actual request and use the logs to confirm whether it reaches the core and where the connection fails.
- Check routing: If you changed routing, test destinations that should go direct and through the proxy. Retest after restoring any temporarily disabled rules.
8. Common questions: reinstalling, administrator access, and log levels
The core still fails to start after reinstalling. Should I reinstall again?
First check whether the same user config and custom routing are still in place. Updating program files doesn’t necessarily remove a config error. Back up your settings, then test with a known-working server config and simple routing. Restore custom settings one at a time instead of bringing back the entire broken config at once.
Do I need to run as administrator to fix this?
Listening on a typical high-numbered local port usually doesn’t require administrator access. First distinguish a port conflict from a directory access error or a network feature that needs extra permissions. Elevating permissions won’t fix JSON punctuation, an invalid field, or a missing collection, and it shouldn’t replace checks of the process and file paths.
The logs don’t show much. Will debug mode help?
Under “Settings” → “Parameter Settings,” find the log level, temporarily set it to debug, then restart and reproduce the issue once. If the config fails before the logging system initializes, check the startup output instead. Restore your usual log level when finished, and remove sensitive connection details before sharing logs.
It works with another node. Does that mean the original node is down?
Not necessarily. The nodes may use different protocols, transports, or security settings, and only one may trigger a config that the current core doesn’t support. Compare the startup logs when switching. If the original node starts normally and only requests fail, check its server address, port, and handshake requirements.
Keep a redacted log that reproduces the issue, along with the core version, the action that triggered it, and what fixed it. Next time, identify the failure stage and the innermost cause first; this is less disruptive than resetting all settings and helps preserve working config. For more help checking the system proxy and application connections, see the troubleshooting guide.