When you get a JSON file generated by a client, first identify which section accepts requests, which selects a route, and which establishes the connection. This guide uses local SOCKS and HTTP inbounds to show how tags connect to routing rules, then explains the difference between DNS lookups during routing, outbound resolution, and lookups performed by the app itself. The example ports are illustrative, not client defaults.
log: logging and config structure
The top level is a JSON object. In the examples here, log, routing, and dns are objects, while inbounds and outbounds are arrays—even when there is only one item. The order of top-level keys does not determine the request path, but array order can matter: rules are evaluated in sequence, and requests that match no rule usually go to the first outbound.
{
"log": {
"loglevel": "warning"
}
}
This is only a logging snippet. For troubleshooting, temporarily set loglevel to info, reload the config, and reproduce the issue once in the same app. After collecting enough detail, restore warning. Set access and error to specify output files for the corresponding logs, but a config loading successfully does not mean the log directory is writable. If the issue occurs during startup, check the client or startup process messages instead of waiting for access logs. Before sharing logs, redact subscription URLs, authentication fields, and any connection details you should keep private.
inbounds: listen address, local port, and tags
The inbound listen and port fields set the listening address and port. protocol determines which proxy protocol the app must use, and settings are interpreted by that protocol. Entering an app's HTTP proxy settings for a SOCKS port will not complete the expected handshake, even if the port is listening. Both examples below listen only on the loopback address and are not exposed to your local network.
SOCKS inbound
- listen
127.0.0.1- port
10808- protocol
socks- tag
local-socks
Enter this port in the app's SOCKS proxy settings.
HTTP inbound
- listen
127.0.0.1- port
10809- protocol
http- tag
local-http
Enter this port in the app's HTTP proxy settings.
Check the listener before changing routing
If a connection to the local port is refused, first confirm that the core is running, no other process is using the port, and the app's address matches the actual listening address. If the request has not reached the core, increasing a routing rule's priority will not help.
outbounds: proxy protocols and the default route
An outbound's protocol determines how an accepted destination connection is handled. freedom is used for direct connections, while blackhole blocks traffic. tag is a reference name within the config, not a protocol: naming a tag direct does not enable direct connections. The protocol in that same outbound determines its behavior.
{
"outbounds": [
{"tag": "direct", "protocol": "freedom", "settings": {}},
{"tag": "blocked", "protocol": "blackhole", "settings": {}}
]
}
- These outbounds let you test direct connections and blocking without a remote account. Before testing, make sure direct connections are acceptable as the default:
directis listed first here. - For a remote outbound such as VMess, the server address, remote port, and user settings belong to the outbound protocol configuration. They are not the local address and port entered in the app's proxy settings. The transport method and applicable security settings must also match the server.
- A subscription URL is an entry point for the client to retrieve config data, not the server address for a core outbound. Updating a subscription or switching nodes may cause the client to regenerate its runtime config, so temporary edits to the generated file may not persist.
routing: tag references and rule order
routing.rules are checked from top to bottom, and the first matching rule determines where traffic goes. inboundTag is an array of inbound tags; outboundTag is a single outbound tag string. When a rule includes multiple match fields, the request must satisfy all of them. The first rule below blocks requests from the SOCKS inbound only when the destination domain is exactly example.org. The second sends other SOCKS requests directly.
{
"routing": {
"domainStrategy": "AsIs",
"rules": [
{
"type": "field",
"inboundTag": ["local-socks"],
"domain": ["full:example.org"],
"outboundTag": "blocked"
},
{
"type": "field",
"inboundTag": ["local-socks"],
"outboundTag": "direct"
}
]
}
}
| Connection method | Destination seen by the core | Expected outbound |
|---|---|---|
| SOCKS | example.org | Rule 1: blocked |
| SOCKS | www.example.org | Rule 2: direct |
| HTTP | example.org | No match: first outbound, direct |
If you swap the two rules, the former second rule will catch all SOCKS requests first, leaving the exact-domain rule with no chance to match. If you swap the outbounds but keep the rules in place, requests with an explicitly assigned tag still follow the same route, but unmatched HTTP requests will use the new first outbound. When troubleshooting misrouted traffic, check the order of both arrays separately; the default outbound is not the last routing rule.
dns: routing lookups vs. app lookups
The top-level dns configures the core's built-in DNS, not the operating system's global DNS settings. Adding dns.servers alone does not automatically take over every app's DNS queries. If an app resolves a domain first and passes only the destination IP to the proxy, routing cannot recover the original domain from that IP alone. Without other domain information, the exact-domain condition above will not match.
{
"dns": {
"servers": ["localhost"]
}
}
Here, localhost uses the machine's own DNS resolution, making it easy to reuse the existing system configuration. It does not start a DNS service on a local port or determine which outbound the final connection uses. To verify a domain-based rule, first check whether the test request passes the domain to the inbound or whether the app has already replaced it with an IP address.
AsIs: The routing stage does not resolve domains just to match rules. Existing IP destinations can still match IP rules.IPIfNonMatch: If a domain destination does not match on the first pass, it can be resolved and checked against IP rules. If an earlier broad rule matches, no additional lookup is performed just because there are IP rules later.IPOnDemand: The domain can be resolved on demand when rule evaluation reaches a rule that requires an IP address. Before changing this strategy, make sure the rule needs to compare the destination address, rather than only the inbound tag.
Troubleshoot config issues: check startup, inbound, routing, and outbound
- First, check which file is actually loaded. Strict JSON uses double quotes, and the final item must not have a trailing comma. The code blocks above show separate top-level fields; do not concatenate them into multiple root objects. If an error points to a field, check its type and whether the core supports it—even if the file is valid JSON.
- Understand the boundary between the core and client settings. In the v2rayN desktop app, check the local listener settings under Settings → Parameter Settings; the exact section may vary by version. Android v2rayNG uses the Xray core, while v2flyNG uses the V2Fly core. Similar basic fields do not mean that extension fields are interchangeable. On Android, traffic handled through the VPN cannot be inferred from desktop system proxy settings.
- Change just one setting in the same test app at a time. First verify a regular request using the correct port, then test the blocked destination. If the result changes after switching the app to an HTTP proxy, check the inbound tag first. If domain and IP requests behave differently on the same inbound, check which form of the destination the app passes to the core.
- Check the outbound connection last. Matching the expected tag confirms that the right route was selected; it does not guarantee the destination is reachable. If a direct connection fails, check local DNS resolution and destination reachability. If a remote outbound fails, verify the remote port, protocol settings, and transport configuration. Change one thing at a time, reload, and repeat the same test to identify which change affected the result.