Advanced v2rayN Configuration Guide
Setup order and validation for subscription groups, routing rules, DNS and TUN.
Before you begin, follow the quick-start guide to import a subscription, select a server and verify the connection. This page does not repeat the installation steps. Instead, it explains settings by configuration layer: which ones only change the server list, which ones affect traffic routing, and which require a restart to take over the network path. If something goes wrong, start with the relevant section rather than changing everything at once.
This guide focuses on the v2rayN desktop client and also covers the limits of v2rayNG and v2flyNG. Interface labels may vary by build. Do not paste the Xray JSON examples into a configuration editor for another core.
01 Configuration baseline and validation order
Advanced configuration starts with a known-good setup, not more rules. First, confirm that your selected server can load a real webpage. Then note its subscription group, system proxy status, routing profile, core type and whether TUN is enabled. You do not need to record subscription URLs or server credentials. These details are enough to identify which layer changes later and to restore the original setup if an adjustment fails.
Separate the client, core and system traffic capture
v2rayN provides the graphical interface, manages subscriptions and generates configuration; the selected core handles the actual connection. The system proxy tells compatible apps to send requests to a local entry point, but it is not itself a tunnel. TUN captures network packets at a lower level, but still depends on correct routing and outbounds. A running status only confirms that the relevant processes have started; it does not prove that DNS resolution, the server handshake or access to the destination is working.
Check the local listening port and active core under Settings; do not guess from a tutorial screenshot. If your browser uses a separate proxy extension, temporarily set it to follow the system proxy. Note whether any apps have their own proxy settings that override the system choice. Otherwise, several traffic paths can coexist on the same computer: one webpage may work while another fails, making routing rules seem unreliable.
Test a small scope before capturing more traffic
Start with TUN off. Select “System proxy → Automatically configure system proxy” and keep a simple routing profile. Test a regular domain, a local network address and the app you actually need, in that order. For the webpage test, open a fresh page rather than refreshing a cached tab. For the local network test, use your own router’s admin address. Do not copy another network’s subnet or use a public service as a local target.
Record which app you tested, what kind of destination it accessed and what error appeared. For example, if a domain fails but the local router page works, you do not need to start by checking every network interface. If only one app fails, check whether it uses its own proxy or encrypted DNS. Note when the error occurred so you can find the corresponding log entry instead of guessing from a long history.
| Configuration layer | Main impact | Check first |
|---|---|---|
| Subscriptions and servers | Connection settings and available servers | Whether the active server works |
| Routing and DNS | Destination matching and name resolution | Matched rule and resolution path |
| System proxy and TUN | How app traffic reaches the core | Capture scope and interface status |
Change one variable at a time
After each change, save your settings, then reload the configuration or restart the service as prompted. Existing connections may keep using the old path after you change server, DNS or TUN settings, so close affected app connections and start fresh requests when testing. Do not change servers, enable FakeDNS and import an entire routing profile all at once. Even if access returns, you will not know which change fixed the issue or whether the other two introduced problems.
When reading logs, distinguish startup errors from request errors. Invalid configuration or a port already in use is a startup issue. A connection timeout, failed name lookup or remote refusal happens during a request. Fix configuration structure or port conflicts first; then trace request errors through the entry point, resolution, rules and outbound. Increase log verbosity only long enough to reproduce the issue. Restore your usual log level afterward to prevent logs from growing indefinitely.
If basic access is not working yet, return to the configuration guide and complete the main setup first. Find installers and platform options on the client download page, or use the FAQ to quickly investigate a specific symptom. The record-keeping approach from this chapter applies throughout: identify which layer changed before deciding what to try next, rather than turning on every setting in turn.
02 Subscription groups and server filtering
Subscription groups organize server sources; they do not split traffic. A group can represent one subscription source or hold manually imported entries. Renaming a group does not change the server’s connection settings. Use names that describe the source or purpose, such as daily subscription, backup subscription or manual setup. Group names are for identification: never include subscription keys, and avoid putting full URLs in notes where they could appear in a screenshot.
Check the group before updating
Under “Subscription groups → Subscription group settings,” check the target group’s URL, enabled status and available filter options. Save your changes, then update from the Subscription groups menu. Check whether the selected command updates the current group or all groups. When multiple groups are configured, the group currently displayed may not be the one the update command affects. After the update, switch back to the target group and check what changed instead of relying only on a completion message.
A subscription URL usually retrieves a set of servers, while a share link represents one connection. Pasting a share link into the subscription URL field does not guarantee that the updater can process it as a subscription. Import a single link from the clipboard using the relevant option under the Servers menu; add a subscription source in the group settings. For details, see Share links vs. subscription URLs.
Display filters and update filters do different things
The main window’s search or group selector usually narrows what is displayed; it does not necessarily delete entries. Filters in group settings may determine which servers are kept during an update. If no servers appear after an update, first clear the main-window search, then check the selected group, and finally inspect the update filter. This order helps distinguish hidden entries from a subscription parsing failure.
Depending on the build, filters may use names or regular expressions. Enter a regular expression only when the field description explicitly says it accepts one; a plain-text filter may not interpret parentheses or pipes. In a regex, HK|JP matches either part, while ^(HK|JP)- requires the name to start with one of those prefixes. Test against a few known names before widening the filter. Differences in capitalization, spaces or full-width characters could otherwise exclude every entry.
^(HK|JP)-
These expressions only demonstrate name-prefix matching. They do not verify a server’s location or automatically select the fastest server. If the source changes its naming format, a filter may stop matching. A region name does not prove the server’s actual exit location; decide what to keep based on the source’s information and your needs. Do not treat complex filters as connection-quality tests or permanently delete a whole set of entries based on one test.
Trace filter failures through the data flow
Break the update process into four steps: fetch, parse, filter and display. If fetching fails, check that the URL works and that the network used for the update is available. If parsing fails, confirm the response is subscription data, not a login page or expiry notice. If parsing succeeds but the list is empty, inspect the filter. If entries exist but are not visible, check the search and selected group. Each step calls for a different fix; repeatedly clicking Update usually adds no useful information.
Keep manually imported entries in a separate group. Refreshing a subscription may rebuild its server list, and changes to a subscription entry’s name or connection settings may be overwritten by the source data. If you need a local revision, copy the entry to a manually managed group first and note why you changed it. A copy creates a separate entry; it cannot reactivate expired credentials or replace an update from the source.
Once the server list is back, check that the active server still points to a valid entry. If an update removed or replaced the old entry, select a server again and verify a real connection. For more failure scenarios, see How to troubleshoot a failed subscription update. Organize groups before moving on to routing; that way, you can tell a wrong server selection from a rule sending traffic to the wrong outbound.
03 Routing rules and match order
Routing rules decide which outbound handles requests that have reached the core; they do not direct app traffic to the client. An app that uses neither the system proxy nor TUN will not start following a domain rule just because you added one. Before making changes, confirm the traffic-capture path as described in Chapter 1. Then open the routing settings under Settings, copy the existing profile for testing and keep the original so you can switch back at any time.
Define the destination before choosing the outbound
Rules can match on domains, destination addresses, ports or inbounds. For a single Xray field rule, multiple different conditions generally all need to match; multiple domains in the same list are alternatives. Putting a domain and an address condition in one rule does not mean “send direct if either one matches.” If you are unsure how conditions combine, split them into separate rules. They are easier to read in logs and to check for overrides.
Rules are checked in order, and the first match determines where traffic goes. Put specific exceptions before broad rules and fallback conditions later. For example, place an explicit direct rule for an internal domain before a proxy rule that covers all domains. If adding a rule makes no difference, check whether an earlier rule already matches before assuming the new rule was not saved. The order shown in the client is part of the configuration, so check it again after importing.
Understand when domain strategies take effect
domainStrategy controls when routing resolves a domain to an address for matching; it is not a global DNS switch for the client. AsIs keeps the domain available for matching first. IPIfNonMatch attempts resolution after no domain rule matches, then checks address rules. IPOnDemand triggers resolution when matching requires address information. Check which values the active core supports; do not copy settings across cores without verifying them.
Here is a LAN direct-connection snippet from an Xray configuration. It shows only the routing field and assumes the configuration already has an outbound tagged direct and the relevant rule data loaded. Merge it into the corresponding place in your existing configuration; do not import it as a complete client configuration. Domain and address rules are separate so you can tell which kind of match applies.
{
"routing": {
"domainStrategy": "IPIfNonMatch",
"rules": [
{
"type": "field",
"domain": ["geosite:private"],
"outboundTag": "direct"
},
{
"type": "field",
"ip": ["geoip:private"],
"outboundTag": "direct"
}
]
}
}
geosite:private and geoip:private rely on rule data available to the core; do not assume they are fixed lists included in every environment. If the logs report a missing data file, check that the rule resources managed by the client are available. For a specific internal domain, use an explicit domain rule. For an actual LAN subnet, specify its address range so unrelated networks are not sent direct as well.
Test an exact rule before expanding its scope
Domain syntax affects the match scope. In Xray, full:example.com matches the exact domain, while domain:example.com can match that domain and its subdomains. Regex matching requires a separate understanding of expression syntax. To match one site, do not use a broad keyword that could catch unrelated domains. Start with the exact domain, confirm the outbound, then extend the rule to subdomains if your use case requires it.
When testing, start a new request and check the corresponding outbound tag. A webpage may load resources from several domains, so a direct connection for the main page does not mean images, login APIs and media use the same path. If only part of the page loads, check the actual failed destinations individually instead of sending every rule through one outbound. If logs show an address but no domain, check whether the app resolved it itself and whether domain information is available.
After changing routing, test a regular webpage, a LAN service and a destination that requires a proxy. Know what each test proves: a reachable server by Tcping does not mean routing or destination access is working. For details, see How to interpret latency test results. A small set of clear rules is usually easier to maintain than several overlapping profiles.
04 DNS resolution paths and configuration
Choosing a DNS server is only one part of DNS troubleshooting. The browser, operating system, proxy core and remote server may all take part in name resolution. Start by asking which component resolves which domain. If the browser uses its own encrypted DNS, changing the system DNS may have no effect. When a domain is sent through the proxy, the local machine may not need to resolve the destination address first. Settings only make sense once you map both the resolution and connection paths.
Distinguish the server domain from the destination domain
If the proxy server itself uses a domain name, its address must be resolved before the connection can be established. That lookup cannot depend on the same proxy tunnel, which is not up yet. The destination website’s domain, by contrast, can be resolved locally by the core or remotely, depending on the configuration. A common loop occurs when DNS requests are routed through the proxy, but the proxy server’s domain needs that DNS service to resolve. If all requests stall after startup, check this dependency before increasing timeouts.
Find the DNS settings under Settings and check which core is active and which fields can be edited. v2rayN may manage DNS settings separately for different cores; similar names do not mean the configurations have the same structure. When using a built-in template, keep its basic structure and change only the upstreams or rules you need. Replacing everything with JSON copied from the web may remove client-generated local listeners, routing links or TUN settings.
Match the resolution strategy to your network
This Xray built-in DNS snippet shows where servers and queryStrategy go, using an upstream specified as an address. Whether that upstream is reachable depends on your local network. The snippet does not automatically send every operating-system DNS request to the core. Use your trusted resolvers, network requirements and full routing setup as a guide; do not treat the example as a universal best setting.
{
"dns": {
"servers": ["1.1.1.1"],
"queryStrategy": "UseIP"
}
}
UseIP allows both address families. Restricting queries to one family can change the path a destination takes. If your network has no usable route for that family, getting an unusable address first may make the initial connection appear to hang before succeeding. Forcing the other family can also break services that depend on the first. Check your interfaces, default route and destination support before narrowing the query strategy.
Regular DNS, encrypted DNS and proxy transport are different things. Encrypted DNS protects the lookup in transit, but does not determine which outbound the website connection uses. Adding a DNS server to a list does not mean its requests will go through the proxy. With an encrypted upstream, also consider how its own domain is resolved and how the connection to it is made. Check the DNS upstream, the outbound used for lookups and the outbound used for destination requests.
Handle internal and public domains separately
An organization’s or home network’s internal domains may only be known to a local resolver. Sending every query to a public resolver may return “not found” or an address unrelated to the internal network. Route specific internal suffixes to a reachable local resolver and keep the LAN direct rules. Some printers and devices use LAN name discovery mechanisms, which cannot be fixed simply by changing public DNS.
| Symptom | Check first | Do not assume |
|---|---|---|
| Only one browser has problems | The browser’s own DNS and proxy settings | All core lookups fail |
| Internal domains fail | Internal resolver and suffix rules | The proxy server must be changed |
| Connections fail just after startup | How the proxy server’s domain is resolved | The destination site is definitely down |
DNS changes involve multiple layers of caching. The operating system, browser and core may each keep their own results. Close existing connections and restart the relevant apps before testing again; if needed, use the system’s cache-clearing tools. The result from a system lookup tool only reflects the path used for that query, not necessarily the result used by the proxy core. When comparing tests, note which lookup tool or entry point you used.
An optimization should have a clear goal, such as resolving internal domains correctly, avoiding useless address-family attempts or removing a resolution dependency loop. Switching the entire DNS setup because one webpage loaded faster can mistake caching differences for an improvement. After each change, keep the app, destination and traffic-capture method the same, then check whether the relevant DNS errors actually disappear from the logs.
05 TUN mode and system traffic capture
TUN receives system network packets through a virtual network interface. It is useful for apps that do not follow the system proxy. It is not a “stronger connection” button and will not fix invalid server settings. Before enabling it, complete the basic tests with the system proxy and note your network interfaces, other tunnel software and LAN access. If something breaks, you can then tell whether the original connection failed or the new system-level capture changed the traffic path.
Check permissions and interfaces first
In the v2rayN main window, find the “Enable Tun” control. Check the TUN settings under Settings, then start it as prompted by the client. Windows may require administrator privileges or a supported service; macOS and Linux may also require system authorization and permission to manage network interfaces. Do not apply driver instructions from another platform. Find installers and platform details on the client download page; check the requirements shown for your build.
After enabling TUN, check the logs for successful interface creation and route setup. If you see a permission error, interface creation failure or device conflict, fix the startup issue before testing websites. Switching servers repeatedly will not help if traffic is not reaching the core. If the interface is up but all connections fail, check the default route, DNS and whether the server address can be reached through the correct interface.
Avoid conflicts between traffic-capture tools
Other VPNs, virtual machine networks, container bridges and security software can all change interface priority or routing. For troubleshooting, do not run several system-wide traffic-capture tools at once. Exit any you do not need, then re-enable TUN. If they must coexist, define which routes handle which destinations. A taskbar icon alone does not confirm a tool has stopped; check the interfaces and routes in system network settings if needed.
The system proxy and TUN can run together when the setup requires it, but test only one traffic-capture method at first. Otherwise, the browser may send requests to the local proxy before the system routing layer handles them, making the path harder to understand. Do not set the local proxy port as the upstream for another proxy layer unless you understand the full chain; a loop can cause connection failures and consume resources.
Test LAN access and name resolution together
After enabling TUN, test your router’s admin page, LAN shares and internal business domains. A failure may mean that a destination was incorrectly routed through the proxy or that an internal domain is now being resolved by public DNS. For the first case, check LAN address rules and system route exclusions; for the second, return to the DNS chapter. Do not add an entire address space to the direct route to fix one device. Confirm the actual subnet and destination, and keep exceptions easy to explain.
When TUN captures the default route, make sure proxy connections do not loop back through the virtual interface. The client usually generates protection rules, but multiple network adapters, network changes or custom settings can alter how they work. If the server connection times out as soon as TUN is enabled and returns when it is turned off, check the server destination’s outbound and the physical network interface. First test with the client’s default TUN settings, then restore custom settings one at a time.
Traffic capture on mobile devices does not work exactly like a desktop virtual interface. v2rayNG and v2flyNG use Android’s connection authorization mechanism; other similar apps may compete for the same slot. Background battery restrictions can also interrupt connections. Per-app proxy settings determine which apps are captured, unlike desktop routing rules. For authorization and background settings, see Android connection authorization and per-app proxy settings.
Confirm the system returns to normal after disabling TUN
After testing, disable TUN normally and check that interfaces, routes and DNS return to their previous state. If the network still has problems after the client exits unexpectedly, restart the client and stop traffic capture normally, then check for leftover system proxy settings. Restore the original state through system network settings if needed. Do not delete interfaces or routes you cannot identify. Retest after switching Wi-Fi networks or waking from sleep; changes to the physical interface may invalidate the previous capture state.
TUN validation should cover at least four things: regular webpages still work, apps that ignore the system proxy can connect, LAN access behaves as expected, and normal networking returns when traffic capture is off. If any one fails, revert to the known-good baseline and trace the issue through interfaces, routes, DNS and outbounds. This order is more useful than repeatedly changing low-level settings.
06 FakeDNS and domain mapping
When an app queries a domain, FakeDNS can return a synthetic address from a dedicated pool and save a mapping between the domain and that address. When the app connects to the address, the traffic-capture path can use the mapping to recover the domain. The main purpose is to preserve domain information for later routing, not to assign a new real address to a website or make an unreachable server reachable. The actual connection still needs to go through the correct outbound.
The mapping must work end to end
FakeDNS needs at least three parts to work together: the query must reach the synthetic-address service, the system must route the returned address back to the traffic capturer, and the core must recover the corresponding domain when handling the connection. Enabling just one part may give an app a synthetic address that it then connects to over the regular network. Check the full path; seeing an address from the pool in a lookup result does not prove FakeDNS is working.
Xray FakeDNS and synthetic-address features in other cores have different configuration structures. v2rayN may use a different core for TUN than for the active proxy connection, so do not assume the TUN configuration uses the same syntax as the core selected for the server. Confirm which configuration layer you are editing and check whether the client provides a matching template. When a supported option is available in the interface, let the client generate the related fields.
Understand the address pool and capacity fields
This Xray top-level fakedns snippet demonstrates the address pool and capacity settings. 198.18.0.0/15 is a special-purpose range, not a real public website address. The snippet does not configure a DNS query entry point, enable traffic capture or restore domains, so it cannot run as a standalone client configuration. Before merging it, confirm that your network does not use this range for internal services.
{
"fakedns": [
{
"ipPool": "198.18.0.0/15",
"poolSize": 65535
}
]
}
ipPool specifies the address range to allocate, and poolSize controls the mapping pool’s capacity. Increasing capacity is not a general speed boost and does not change remote bandwidth; it affects the resources needed to maintain mappings and how many entries can be held. If your network visits many different domains, observe actual usage rather than setting an arbitrarily high value. Changing the pool can also affect results already cached by apps.
Compatibility issues often come from bypasses and caches
Some apps use encrypted DNS of their own, bypassing FakeDNS and connecting directly to real addresses. Others pass lookup results to child processes that do not go through the traffic capturer, leaving no chance to restore the synthetic address to a domain. Some apps check address types and may reject special-purpose ranges. For affected apps or domains, keep a real DNS path and confirm routing exceptions instead of repeatedly changing the address pool.
Handle internal domains with care. If a domain is used to reach a local device, returning a synthetic address and routing it through the wrong proxy outbound will break LAN access. Check whether the name needs a real address and whether a local DNS server answers it, then configure the appropriate exclusions. Synthetic-address exclusions, DNS upstream selection and LAN direct routing are separate layers; changing one does not automatically configure the other two.
Use a side-by-side test to decide whether to keep it
For a fair test, keep the same server, routing rules and app, then compare regular DNS with FakeDNS. Check whether domain rules match consistently, the destination connects and LAN access remains normal. Do not compare a single page-load time: caching, connection reuse and server load can all affect the result. If FakeDNS does not solve a specific problem but adds compatibility exceptions, regular DNS is usually easier to maintain.
In the logs, check whether the domain is recovered and the selected outbound is correct; the synthetic address alone is not the point. Mapping information may be runtime state, so do not assume old mappings survive a core restart. If an app keeps an old result for a long time, connections may fail only after a restart. Make the app resolve the domain again before changing the configuration.
Introduce FakeDNS only after regular DNS, TUN and routing are stable. Then, if something breaks, you can roll back just the added layer. If your build has no clearly supported setting or complete configuration instructions, do not force a snippet for another core into the template. Keep a clear, real-resolution path until there is a specific reason to experiment further.
07 Managing multiple subscriptions and update strategies
With multiple subscription sources, focus on traceable origins, controlled updates and isolated failures. Do not copy every server into one group with no source information. Although the list may look simpler, it will be hard to tell which entries have expired when an update fails. Use a separate group for each source, plus a group for manual configurations. Keep notes to purpose and maintenance details, and use the designated field for subscription URLs.
Set update scope and update route separately
First decide whether to update the current group or all groups, then choose an update method provided by the client. Some sources can be fetched directly; others need an already-working proxy connection. This controls the network path used for the subscription request, not the default route for servers after the update. Before changing the update method, make sure the existing connection used to fetch the subscription still works. Otherwise, you can end up in a loop where you need a new server to update the old one.
If the main subscription is unavailable and updating it depends on its active server, switch to a verified backup connection or fetch it directly if the source allows. Do not rely on an untested entry as a recovery tool. Keep at least one independently verifiable fallback and note its source and conditions for use. A fallback is valuable because it reduces dependencies, not because it adds more servers with similar names.
Avoid frequent updates and duplicate imports
Updating a subscription is not a connection retry. If the source has not changed, repeated refreshes usually fetch the same settings again and may trigger rate limits. Set automatic update intervals based on the source’s guidance and how often it changes; use manual updates to check for setting changes. If a connection fails, identify the error first: invalid credentials, a remote timeout and a failed subscription fetch are different problems that require different fixes.
Adding the same source multiple times can create duplicate entries. Before cleaning them up, check whether the group URLs match, whether they have different filter settings and which copy contains the active server. Duplicate names do not guarantee identical entries; server addresses, transport settings and authentication details may differ. Do not bulk-delete by display name. Keep known-working entries first, then organize one group at a time.
Keep manual changes separate
The source maintains subscription entries, and an update may overwrite local changes. If you need to change transport settings, a server address or a display note, copy the entry to a manual group first and note what you changed. If the source changes its settings later, the manual copy may not be updated; check it against the source periodically. Keeping manual copies separate both prevents updates from overwriting your changes and makes clear that you are responsible for maintaining them.
| Entry type | How to maintain it | Main risk |
|---|---|---|
| Source subscription | Separate group; update by source | URL expires or settings are replaced |
| Backup subscription | Verify independently; keep a fallback path | May stop working if left untested |
| Manual copy | Document changes; check for updates yourself | May drift from source settings |
Use a consistent order for a full maintenance session: back up the current settings, update one source, check the entries, verify the active server, then move on to other groups. Do not update every source and immediately deduplicate, change filters and switch routing. Separating actions makes it clear which step caused a change, even if a source returns unexpected data, and keeps the whole server list from becoming an unknown state at once.
A backup group does not mean automatic failover
Having several entries in a group does not mean the client will automatically pick a working server. Check the active server, the outbound used by routing and any selection policy separately. Some tests only show that a handshake is reachable; they do not prove that a real destination can be reached. Download speed tests also reflect throughput at a particular time. For testing limitations, see Tcping vs. real connection latency.
After managing subscriptions, leave a brief maintenance note: which groups updated successfully, which were deferred, whether the active server was reverified and whether any manual copies need follow-up. Record status only; do not include sensitive details. This lets you pick up from the last known state next time instead of reorganizing the whole list. Troubleshoot update failures using the same four steps—fetch, parse, filter and display—regardless of how many subscriptions you have.
08 Custom outbounds and configuration rollback
Use a custom outbound when the graphical interface cannot express what you need and you can explain the full connection path. First define the goal: a separate direct outbound for certain destinations, or a more complex forwarding chain. If you only need one domain to connect directly, use the routing editor instead of replacing the whole configuration. Custom settings add flexibility, but also make you responsible for field compatibility, tag references and maintenance after updates.
Confirm which configuration you are editing
In v2rayN, regular server entries are generally used by the client to generate the runtime configuration. Custom configurations may preserve more of the original structure, so do not assume that both behave the same way in the interface. Before using a custom-configuration option under the Servers menu, confirm whether it expects a complete file or a reference to an existing one, and choose the matching core. Being able to import a file does not mean the active core accepts every field in it.
Before editing, copy a known-working file and make changes to the copy. Xray and V2Fly share some concepts, but check their fields and extensions separately. Outbound types and routing structures from other cores are not interchangeable either. First inspect the top-level fields, inbound listeners and outbound tags, then add the new feature. Replacing a client-generated inbound at the outset can leave the system proxy pointing at the old port and make the entire client appear broken.
Understand tag references with a minimal example
This Xray snippet defines a direct outbound and a reject outbound, then sends an example domain to the reject outbound. It includes only outbounds and routing, with no local listener, so it is not a complete runtime configuration. When merging it, keep the existing proxy outbound and any required rules, and avoid reusing a tag that already exists. The example demonstrates how references work; you do not need to block a real business domain.
{
"outbounds": [
{
"tag": "direct",
"protocol": "freedom",
"settings": {}
},
{
"tag": "reject",
"protocol": "blackhole",
"settings": {}
}
],
"routing": {
"rules": [
{
"type": "field",
"domain": ["full:example.com"],
"outboundTag": "reject"
}
]
}
}
Here, outboundTag must exactly match an outbound’s tag. A display name and a tag are different things; a spelling or capitalization change can break the reference. In common Xray configurations, traffic that matches no rule uses the first outbound, so changing array order may also change the default behavior. When merging a snippet, check that existing default outbounds still behave as intended, not just that the new rule is present.
Map dependencies before configuring complex forwarding
For a multi-hop connection, first write down the local entry point, first hop, subsequent connections and final destination. Be able to explain which resolver handles each server domain and which outbound establishes each connection. Different cores use different fields to implement forwarding; do not configure it based only on the phrase “upstream proxy.” If a hop depends on itself, the result may be a recursive connection or a startup failure.
Check the file’s JSON syntax first, then validate its meaning to the core. JSON does not allow comments or trailing commas; escape backslashes and double quotes correctly in strings. Even valid JSON may contain unsupported fields, missing tags or unavailable rule data. Find the first meaningful error in the client logs and fix the startup failure before investigating later connection messages, so repeated errors do not obscure the cause.
Make recovery part of the acceptance test
After startup succeeds, test a minimal destination, then a regular request and a LAN request that worked before. The logs should show the expected outbound, not merely an absence of errors. If the custom setup replaced the original configuration, also check for leftover local ports after turning off the system proxy or TUN. Make sure there is a clear way to restore the original setup; do not rely on remembering a few temporary toggles.
After updating the client or changing cores, revalidate custom fields and default behavior. Keep the working configuration and migrate a copy; do not layer a new template directly onto your only configuration. If the graphical routing, DNS or group-management settings can meet your needs, consider returning to a client-managed setup to reduce manual maintenance. Custom configuration should solve a specific problem, not become a maintenance project of its own.
The order of this guide is also a troubleshooting order: check the server and entry point first, then routing and DNS, and finally TUN, FakeDNS and custom connection paths. For the basics, return to the quick-start guide; for common issues, see the FAQ; for client options and installation, visit the download page. Keep one verified setup as a baseline so you have a reliable point of comparison for the next change.