Advanced Guide · Configuration & Troubleshooting

V2Ray Advanced Configuration Guide

From subscription management to traffic capture, find settings by topic, verify the results, and decide whether to keep each change.

If you’re installing for the first time or haven’t connected yet, start with the Quick Start Guide to import a profile, connect, and verify that it works. This page is a reference guide; you don’t need to enable features in order. Use v2rayN as the primary desktop client and v2rayNG as the primary Android client. v2flyNG is an alternative that uses the V2Fly core. Choose an installer for your operating system and processor on the client downloads page.

Subscription Groups & Server Filtering

First, identify the server’s group

A subscription is a source that periodically fetches server configurations; a group is the list view the client uses to organize them. In v2rayN, open “Subscription Group → Subscription Group Settings,” check the alias and subscription URL, then return to the main window and select the group. In v2rayNG, open “Subscription Group Settings” from the sidebar, add or edit an entry, then return to the list and select “Update Subscription.” Depending on the interface, the update command may be in the overflow menu or may apply to the current group or all groups. Read the command label before using it—don’t assume the update is limited to the group currently shown on screen.

A group is neither an outbound nor an automatic switching policy. Selecting a group only changes which entries appear in the list; the active configuration may still belong to another group. After an update, find the server you were using and check whether its address, protocol, or transport settings changed. If the entry was replaced, select a suitable one, apply it or reconnect as required by the client, then verify an actual request. A highlighted list entry, a running-service icon, and an outbound label in the logs each indicate different things. Don’t rely on just one to confirm that a switch worked.

Distinguish list search from import filtering

Search is useful for quickly finding a server: enter a short keyword, select the entry, then clear the search box to show the rest of the list. Import filters apply during updates and may determine which entries are kept. If an entry seems to be missing, switch to the full list and clear the search first, then check whether a filter is configured for that subscription. If you’re unsure whether filtering works the same way in older and newer interfaces, don’t experiment on your primary group. Use a temporary group with a few easy-to-identify test entries instead.

Use the syntax below only when the setting explicitly supports regular expressions. This example matches names beginning with Office- or Test-; add anchors at the start or end only if needed. Results will differ if the field matches an address or the full configuration rather than a remark. Also check whether the field means “keep matching” or “exclude matching”: the same pattern can produce the opposite import result. If the interface doesn’t specify the field or filter direction, test with a short word you know should match. Don’t assume it uses the same syntax as list search.

^(Office|Test)-

Base filters on stable prefixes, not promotional text or temporary status labels added by a provider. Parentheses, square brackets, and vertical bars have special meaning in regular expressions. If you’re looking for a remark that contains brackets, confirm it with ordinary search first, then escape the characters as required by the field. After changing a rule, test three kinds of entries: ones that should remain, ones that should be excluded, and similar names that shouldn’t be affected. Checking only whether one target appears can miss accidental matches or removals.

What to check when an update returns no entries

First check whether the update succeeded; then check whether entries were filtered out. If the URL request fails, the client may keep showing the previous list or show no results, depending on how it handles the error. Check whether the message indicates a connection timeout, permission denial, or content parsing failure. If the response is a login page or other text, changing the filter won’t help. Subscription URLs may contain access credentials, so don’t include the full URL when saving or sharing logs.

If the client reports a successful update but shows no entries, save the filter text, then temporarily clear the filter in a test group and update again. If entries reappear, the source is reachable; narrow down the matching rules one at a time. If the list is still empty, check the subscription’s response format and whether the client supports it. Being able to import a single server doesn’t mean the client can parse a subscription containing that server. Check “URL is reachable,” “content can be parsed,” and “entries can start” separately to avoid mistaking an update problem for a server quality issue.

Routing Rules in Practice

Start with one clear rule

Routing determines which outbound handles connections received by the core. In desktop v2rayN, open “Settings → Routing Settings” and check the active routing profile. In v2rayNG, open “Settings → Routing Settings” and review the predefined rules or available custom options. Editing a rule doesn’t mean the new profile is active: check the active profile after saving, and restart the service if the interface requires it. Some interfaces generate rules by category, while others allow individual rules to be edited. Confirm the order of raw rules in the running configuration.

With typical core matching behavior, rules are checked from top to bottom, and the first match determines where traffic goes. Put specific exceptions before broad rules. For example, to send example.org and its subdomains directly, add the following rules to the existing raw core configuration. The example also sends private IP addresses to the direct outbound, which assumes an outbound tagged direct exists. This is a routing object and its enclosing key—not a complete, standalone configuration or a paste-ready format accepted by every client rule editor.

{
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "domain": ["domain:example.org"],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "ip": ["geoip:private"],
        "outboundTag": "direct"
      }
    ]
  }
}

domain: matches on domain boundaries, making it suitable for a domain and its subdomains. full: matches only the exact domain specified, making it suitable for a single service. The example’s geoip:private requires the runtime to provide the relevant rule data. If that data is missing, startup may fail. To test a single authorized device, you can instead specify its known IP range. Don’t assume traffic will go direct when no rule matches: raw core configurations typically use the first outbound as the default, while graphical clients may generate a fallback rule of their own.

Distinguish domain targets from IP targets

For the same site, a client may send the domain to the proxy, or an app may resolve it to an IP address before connecting. If the core receives only an IP address, ordinary domain rules can’t match the original domain. Check the destination passed to the inbound and any available sniffing information instead of repeatedly changing the domain pattern. Sniffing depends on the inbound settings, protocol, and connection contents; it can’t be relied on to recover every original domain. To test, access the domain and a known direct IP address separately.

AsIs doesn’t resolve domains to IP addresses for routing decisions. If you need to try IP rules when no domain rule matches, consider IPIfNonMatch. If a domain needs to be resolved before rule matching begins, look into how IPOnDemand works. These strategies add DNS results and lookup time to the routing process; they aren’t general-purpose speed optimizations. Verify domain matching with AsIs first, then decide whether to add IP-based matching.

Verify rule order with controlled requests

Prepare one target that should go direct, one that should use the default outbound, and a similar domain that shouldn’t match. Keep the server, network, and traffic-capture mode the same, and change only one rule. Close existing connections or restart the test app before making a new request, then compare the destination and outbound label in the connection logs, if available. Existing connections often keep their original route; refreshing a page may not create a new connection.

If both requests use the same outbound, check broad rules higher up first, then the tags, active profile, and actual inbound. Some clients show domain and IP lists separately without necessarily generating a single rule that requires both to match. In a raw configuration, multiple conditions in one field rule typically all have to match. To match a domain or an IP address, split the conditions into two rules as shown in the example. If the client is running but webpages won’t load, use the Connected but Can’t Browse? Troubleshooting Checklist to check each step from inbound to DNS resolution.

DNS Configuration

First identify what is making the DNS request

DNS changes can take effect at the wrong layer. The operating system has its own resolution path, browsers may use their own secure DNS, and the core can maintain separate DNS settings. If v2rayNG has a “Local DNS” option under “Settings,” check its status and the current network mode first. Enabling it doesn’t mean every app’s independent DNS requests will go through the core. In v2rayN, check the DNS settings under “Settings” and confirm whether they apply to a standard core configuration or the network configuration used by TUN.

With a system proxy, a browser may send requests containing domain names directly to the proxy, while a command-line DNS lookup still uses the operating system’s resolution path. An app may also resolve a destination first and then send the request through the proxy. So a successful command-line lookup proves only that particular DNS path works; it doesn’t confirm that the client’s built-in DNS or the browser’s independent DNS works. For each test, note the app, traffic-capture mode, target, and logs you’re checking. Don’t compare results from different paths as if they were the same.

Choose a reachable resolver before deciding how to split queries

On a corporate network, internal resolvers often handle internal domains that public recursive resolvers don’t know about. Preserve a working path for internal domains before deciding whether public domains need a separate resolver. The following minimal dns fragment for a raw core configuration is only for testing public-domain resolution. It doesn’t change the operating system’s DNS settings or intercept queries from apps. First confirm that the recursive resolver shown is reachable and allowed on your network. On managed networks, use the address provided by your administrator.

{
  "dns": {
    "servers": ["1.1.1.1"],
    "queryStrategy": "UseIP"
  }
}

UseIP doesn’t restrict results to a single address family. If you have evidence of a routing issue with one address family, temporarily compare UseIPv4 or UseIPv6 on a core that supports the setting, then restore the original value after testing. Restricting the address family returned by DNS doesn’t disable the other address family across the operating system, nor does it fix a destination IP hard-coded in an app. On dual-stack networks, investigate DNS lookup time, initial connection time, and retries after failure separately if webpages are occasionally slow.

Encrypted DNS protects queries in transit to the resolver, but still needs a working connection path. If the resolver is specified by hostname, consider how that hostname itself will be resolved. If reaching the resolver depends on the proxy that’s still starting up, you can create a loop. Establish a baseline with a known-reachable DNS path that meets your network’s requirements, then add encryption or split queries by domain. Retest both internal and public destinations after every added layer.

Distinguish cached results, DNS responses, and connection failures

When testing system DNS, first check whether the domain returns the expected record type, then use the same app to access the service. Old responses may be cached by the browser, operating system, or core; restarting one won’t clear the other two. Try another test domain known to be served by the same resolver to see whether the result is caused by a cache. If resolution is correct but access fails, check routing, the destination port, and the actual outbound. Don’t keep changing DNS just because the error mentions a domain.

Distinguish three kinds of errors: a query timeout means no response arrived in time; a nonexistent-domain response means the resolver returned a definite result, but not necessarily from the right DNS view; and an IP address that won’t connect points to the destination network or connection path. If only internal company domains fail, first check whether their queries are going to a public recursive resolver instead of sending all traffic through the same DNS path. If the browser uses its own DNS, record the original setting and make reversible comparisons in line with your organization’s policy.

TUN Mode

Choose between a system proxy and TUN

A system proxy tells apps that honor the system settings where to send requests, usually without changing the device’s overall network routing. TUN uses a virtual network interface to receive IP packets routed by the operating system, then lets the client handle the connections. For a browser or desktop app that supports proxies, start with the system proxy. Consider TUN when an app doesn’t use the system proxy and the environment allows a virtual interface. A wider capture scope doesn’t mean every traffic type or connection will be handled by the same rules automatically.

Platform settings and key checks
PlatformWhere to lookCheck first
Windowsv2rayN TUN switch and system network settingsWhether the app has permission to create an interface and set routes
macOSv2rayN TUN settings and system network interfaceWhether the current build provides the option and the system permits traffic capture
Linuxv2rayN TUN settings and system routesWhether the runtime allows TUN devices and route changes
Androidv2rayNG VPN mode and per-app proxySystem VPN permission and whether apps are included in the selected scope

Desktop TUN and Android traffic capture through a VPN service have some similar things to check, but their interfaces, system permissions, and configurations aren’t interchangeable. Android usually asks the system for permission the first time it starts. If another VPN service is already active, check whether switching will interrupt a work connection. If you can’t find the TUN switch on desktop, check the client, build, and system options in use. Don’t copy permission commands from another platform or disable system security settings to troubleshoot.

Record the original network state first

Before enabling TUN, confirm that the current server works with TUN off, then note whether the system proxy is disabled, manually configured, or managed by the client. If you need to test a LAN printer, file share, or internal system, record a known working target and the results for both its domain and direct IP address. Then enable TUN without changing the server, DNS, or routing profile at the same time. If one app starts working while another service stops, you’ll know the change in traffic capture is relevant.

After enabling TUN, check that the virtual interface and runtime logs look normal, then inspect the local routes. The commands below show which route Linux and macOS use to reach an address; they only read system state. Run the command for your operating system. The target is an example public IP address; for an internal network, use a specific address you’re authorized to test. This shows the system’s route selection, not the outbound ultimately selected by the core. Check those two layers separately.

# Linux
ip route get 1.1.1.1

# macOS
route -n get 1.1.1.1

Troubleshoot LAN access and conflicting traffic capture

If only internal network access fails after enabling TUN, test a direct IP address and the hostname separately. If both fail, first check whether the target is entering the virtual interface and whether the client has preserved a working path to that subnet. If only the hostname fails, investigate DNS or whether local service discovery still uses its original path. If the target subnet overlaps with another virtual network, a generic “bypass LAN” option may not tell you which system route takes precedence. Record the actual subnet and interface, then make a targeted change. A direct rule in the core can’t restore a system interface that’s already unavailable.

The server connection itself also needs a working underlying route. If all connections fail after enabling TUN, check whether requests from the client to the server are being sent back into TUN and whether another traffic-capture tool is active. Prefer the client’s interface-selection and route-management features; don’t stack global routing scripts from unknown sources. On Android, if only some apps fail, check the list and mode under “Per-app proxy,” then restart the affected app. Don’t mistake an old connection retained by a background process for an ineffective configuration.

To roll back, turn off traffic capture and confirm that the virtual interface and routes have been restored. Then restore the system proxy to its previous state. If a browser still connects to a local proxy port after closing the client, check for a leftover manual proxy setting. If a problem appears only after switching Wi-Fi networks or resuming from sleep, reproduce it with the same network change. If Android disconnects only after the screen turns off, see the Battery Optimization and Background Activity Guide and first check whether the system is stopping the background service.

FakeDNS

Understand how synthetic addresses work

FakeDNS returns a synthetic address from an address pool for a domain and records the mapping between them. The app then connects to the synthetic address. If the connection also enters a processing path that knows about the mapping, the core can recover the domain and continue routing. A synthetic address is an internal marker, not the address the destination server actually provides to the outside world. Testing connectivity directly to it, or asking another machine to connect to it, can’t tell you whether the original site is reachable.

FakeDNS is useful when an app resolves a domain first and then passes only the address to the traffic-capture layer, while routing still needs to match the domain. Enabling a DNS setting alone isn’t enough: the component returning synthetic responses, the component receiving subsequent connections, and the domain-recovery mechanism all need to work together. If later packets leave through a physical interface or go to a separate process that doesn’t share the mapping, it’s expected that the synthetic address won’t open the service. Without a specific need, ordinary DNS with domain-based routing is easier to verify.

Check the address pool, query path, and inbound

First confirm that your client and running core support FakeDNS configuration. In a graphical interface, check the generated settings through the options it provides. For a raw Xray configuration, you can define an address pool under fakedns. This example shows only that field; it doesn’t include the DNS settings that return synthetic responses or the inbound that recovers the domain. Adding this fragment alone won’t make all normal DNS responses on the device synthetic addresses.

{
  "fakedns": [
    {
      "ipPool": "198.18.0.0/15",
      "poolSize": 4096
    }
  ]
}

ipPool defines the allocation range, and poolSize sets the mapping pool capacity. Neither setting controls bandwidth, concurrent connections, or the number of domains you can access. Before choosing a pool, check whether the current network, other virtual interfaces, or test environments use an overlapping subnet. On a dual-stack network, also confirm that your client supports the selected IPv6 pool and check how the query path handles A and AAAA records. Don’t assume dual-stack traffic will use the mapping in the same way just because one IPv4 test worked.

In a raw Xray configuration, you also need to select fakedns among the built-in DNS servers and check the relevant options under sniffing.enabled and sniffing.destOverride on the inbound that receives subsequent connections. If you rely on the desktop client’s TUN network engine, check that engine’s own configuration too. The same feature name in both places doesn’t mean their fields are compatible. Preserve real DNS resolution for internal services, especially printers, local domains, and devices outside the traffic-capture path.

Verify responses, traffic capture, and domain recovery in order

First, use a controlled test domain to check whether the app receives an ordinary address or one from the pool. Then confirm whether a new connection to that address actually enters the expected interface. Finally, check the connection logs for the recovered destination or expected outbound. If the app receives a real address, check whether it uses another resolver or has a cached result. If it gets a synthetic address but no connection appears in the logs, check the interface and routes. If a connection appears but the domain isn’t recovered, check the inbound settings and whether the mapping belongs to the same runtime session. These three outcomes require different troubleshooting steps.

If the problem appears after a restart and then goes away, check whether the app still holds a synthetic response from before the core rebuilt its mapping. Close the test app’s existing connections, clear the relevant cache as your environment allows, and test with a new request. To roll back, stop returning synthetic addresses and confirm that old cache entries no longer direct the app to the address pool. Simply disabling the path that receives synthetic addresses can leave cached responses causing a brief outage.

Managing Multiple Subscriptions

Name groups for their purpose, not their temporary status

If you use more than one subscription, agree on group names before importing them. Choose names that explain both source and purpose, such as “Work - Primary” or “Test - Backup.” Avoid generic names like “Group 1” or “Group 2,” and names based only on speed. Server remarks may be duplicated, and external sources can change remarks when they update. To determine whether two entries are equivalent, compare at least the address, port, protocol, transport, and security settings. The same address doesn’t guarantee the same authentication parameters, domain settings, or transport path.

In v2rayN, create a separate entry for each source under “Subscription Group → Subscription Group Settings.” On Android, check each source and alias under “Subscription Group Settings” in your client. Keep manually configured entries separate; don’t expect local changes to imported entries to survive a subscription update. If you need a verified configuration for comparison, save it separately in a way your client supports and maintain it independently. That way, the test baseline and the configuration under test won’t both be replaced by the next update.

Make refreshes a verifiable process

When adding a new source, update that group first, check that the number of entries matches the source’s documentation and that the protocols are supported, then test one entry. For routine updates, refresh the backup group before the primary group when possible. If the client only supports updating all groups, note the active entry and keep a working configuration outside the subscription update scope. If automatic updates are available, set the interval according to how often the source changes and when you need it. Shortening the interval won’t fix intermittent failures.

Some interfaces distinguish between updating “through the proxy” and “without the proxy.” These options change the request path used to fetch subscription data; they don’t determine which outbound updated servers use. If a source fails to refresh, first check whether its URL is reachable and whether the current path can resolve and connect to it. Don’t change the update method, active server, and DNS at the same time; if the update starts working, you won’t know which change helped. If the usual update path fails only when the primary configuration is unavailable, check whether another verified path can be used, subject to your network’s access policies.

A successful update may only mean the data was downloaded and parsed; it doesn’t prove that a server works. First check whether the active entry changed, then make a new request with the same app. Latency tests are useful for an initial comparison, but their method, destination, and route may differ from actual usage. Don’t choose a long-term server based on the lowest reading from a single test. If speeds are unstable during peak hours, use the Layered Troubleshooting Guide for Slow Speeds to compare servers, routes, and local settings instead of deleting every subscription and starting over.

Distinguish a failed source, a failed entry, and a local settings issue

If only one subscription fails to update while others refresh and existing entries still connect, check that source’s URL and access permissions first. If multiple sources can’t refresh but imported configurations still work, investigate the update path and DNS settings they share. If an update succeeds but no new entries start, check which protocols and transport settings were generated after parsing, then confirm that the current core supports them. If entries from different sources start but business apps all fail, look again at local traffic capture, routing, and DNS.

When cleaning up old groups, switch to a verified new configuration first and use it for a while before removing sources you no longer maintain. Before deleting anything, check whether the command removes the subscription definition, the current entries, or both. Use the same approach when migrating devices: rebuild a minimal working group on the new device, then add other groups and local rules one at a time. A configuration that works on desktop may not run unchanged on a phone. Parsing the protocol, starting the outbound, and capturing system traffic are three separate checks.

Access parameters in a subscription URL are credentials, not ordinary remarks. For troubleshooting, sharing the group name, update time, and a redacted error type is usually enough. Exported configurations, QR codes, and screenshots may also contain sensitive fields. For the next person troubleshooting, record enough to identify the group, when it was updated, how it was tested, and how to roll back. There’s no need to store the full subscription URL in routine troubleshooting notes.

Custom Outbounds

First decide whether you need a raw configuration

For a standard server entry, the client generates an outbound from the fields in its interface—suitable for routine imports, switching, and updates. Consider a custom outbound only when you need a separately named route, a rule that explicitly targets it, or a configuration combination the interface doesn’t provide. In v2rayN, first confirm that you’re using an option that imports or runs raw configurations; don’t paste the entire JSON into a regular server address field. v2rayNG and v2flyNG use different cores, so you can’t infer field support from menu names alone.

A custom configuration involves at least three parts: the inbound receives local requests, routing selects an outbound based on conditions, and the outbound defines how to connect to the destination. Tags link them together. Tags have no protocol meaning, so check the actual protocol of an outbound named direct. A route pointing to a nonexistent tag won’t work as intended. Choose names that explain their purpose and avoid tags generated by the client. Before making changes, save a verified configuration separately and note the client’s traffic-capture mode and local listening port so you can restore the original setup.

Use two simple outbounds to test tags and the default route

This is a minimal, standalone test configuration for cores that support these raw fields. It doesn’t set up a system proxy or capture traffic from the whole device; it opens a SOCKS inbound only on the local loopback address. The default outbound is freedom, while matching requests for example.org go to blackhole. Use it to test outbound selection, not as a replacement for your everyday configuration. Before starting, confirm that the example port isn’t already in use.

{
  "inbounds": [
    {
      "tag": "check-in",
      "listen": "127.0.0.1",
      "port": 10880,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": false
      }
    }
  ],
  "outbounds": [
    {
      "tag": "direct",
      "protocol": "freedom",
      "settings": {}
    },
    {
      "tag": "blocked",
      "protocol": "blackhole",
      "settings": {}
    }
  ],
  "routing": {
    "domainStrategy": "AsIs",
    "rules": [
      {
        "type": "field",
        "domain": ["full:example.org"],
        "outboundTag": "blocked"
      }
    ]
  }
}

Once the configuration is running, use a SOCKS-capable test tool and pass the domain to the inbound instead of resolving it in the tool first. Run the two commands below in a terminal with curl installed. Judge success or failure against your network baseline and the core logs. If the network is reachable, the first request should use the blocking outbound and the second should use the default outbound. If the client’s traffic-capture tool has set environment variables or a proxy bypass list, make sure the requests actually go through the example port.

curl --noproxy "" --proxy socks5h://127.0.0.1:10880 --max-time 10 https://example.org/
curl --noproxy "" --proxy socks5h://127.0.0.1:10880 --max-time 10 https://example.net/

Troubleshoot startup, inbound, and outbound separately

If the configuration won’t start, check the JSON structure, field compatibility, and whether the port is already in use. If the logs say a tag can’t be found, check its capitalization and whether it actually appears in the running configuration. If the configuration starts but both requests immediately fail to connect locally, check the listening address and port rather than changing remote transport settings. If only the default-outbound request fails, check whether the test destination is reachable without the local proxy, then review the core’s DNS and connection errors. Loopback binding is a limit of this example; don’t expose an unauthenticated inbound to the whole network just to make testing from another device easier.

When merging test rules into your everyday configuration, preserve the existing outbound order. Add a specific, narrowly scoped rule first, then decide whether you really need to change the default route. A custom configuration may run as a separate entry in the client rather than being merged automatically with the selected subscription server. Conversely, some interfaces may regenerate routing or inbounds. Use the running configuration and request results as your evidence, not the file as it looked before import. If a port or tag conflicts with the existing configuration, change one item in the test configuration rather than renaming every related entry.

When you’re done testing, stop the test configuration, restore the original active entry, and make a new request using the original system proxy or VPN mode. If you need to explain a change to a colleague, share only a redacted minimal configuration and expected route, and state whether the example is complete and which core it supports. For unfamiliar terms or fields, consult the Glossary. To return to the basic connection flow, use the Quick Start Guide to verify importing, selecting, and connecting.