V2Ray Advanced Configuration Guide

Build a configuration workflow you can roll back

Break each issue into an entry point, a decision, and an exit

Advanced configuration becomes confusing not because one parameter is necessarily difficult, but because several layers can change at once. A complete connection passes through at least three stages: application traffic enters through the system proxy or a virtual network interface; the core matches routing rules using the domain, IP, port, and process information; finally, a proxy, direct connection, block rule, or custom outbound handles the traffic. Subscriptions provide remote servers, routing decides where traffic goes, DNS resolves domains to addresses, and TUN changes how traffic enters the core. Keep these four layers separate and troubleshooting will not require repeatedly reinstalling the client.

For example, if a browser connects but a command-line tool does not, start with the entry layer: the browser may read the system proxy while the terminal program connects directly. If the regular proxy works but TUN causes problems, check the virtual interface, routing table, and DNS interception first. If one domain consistently takes the wrong route, inspect rule order instead of immediately changing subscriptions. A domain may resolve successfully while the connection still fails, so distinguish an incorrect resolution result, an unreachable outbound, and mismatched protocol parameters. Mapping symptoms to layers is the most important method in this guide.

Change one variable at a time

Before experimenting, preserve the current working baseline. Record the selected server, system proxy status, routing mode, DNS mode, and TUN state; if the client supports configuration export or backup, save a copy. Then change only one related group of settings at a time and verify it immediately. Do not enable TUN, switch DNS, import new routes, and change servers in one operation. When four things change together, even a restored connection does not reveal which change helped; if the connection breaks, the cost of isolating the cause multiplies.

Verification should also be layered. First check the client log to confirm that the core started normally, then check the local listening port or virtual interface, test domain resolution, and finally test the target application. The first error in the log is often more useful than the cascade of errors that follows. If the core rejected the configuration format, later connection timeouts are merely consequences. System commands can help inspect basic state, but their output only describes what the operating system currently sees and cannot replace the client log.

Windows:
ipconfig /flushdns
ipconfig /all

macOS:
scutil --dns
route -n get default

Linux:
resolvectl status
ip route

Prepare a stable set of test cases

Your test set should cover three kinds of requests: a site expected to connect directly, a site expected to use the proxy, and a domain used only to check DNS. Avoid changing test targets frequently, or fluctuations in the target service will complicate the diagnosis. In a browser, first disable extensions that may manage proxy or DNS independently, and check the browser’s own secure DNS setting; in a terminal, explicitly determine whether HTTP_PROXY, HTTPS_PROXY, and ALL_PROXY environment variables are being used. Different programs enter the proxy chain in different ways.

Record timestamps before and after each change. v2rayN logs continue to scroll, so accurate operation times help locate the corresponding requests. If the log shows only an IP address and no domain, the application may have resolved the domain before it reached the core; a domain-only routing rule may not match, so inspect sniffing, DNS, or IP rules. If the log shows the expected domain but the wrong outbound is used, check rule priority and tags. Once this baseline is established, every later chapter can use the same rollback and verification method.

Subscription groups and server filtering

Use groups to isolate sources, not to pile up labels

v2rayN can store manually added servers and multiple subscription sources at the same time. As the server list grows, the first question is not “how do I display more?” but “how do I keep each source traceable?” A practical rule is to assign one subscription URL to one subscription group and name the group by its purpose or source; avoid names such as “Subscription 1” or “Backup 2.” When a batch of servers has bad parameters, duplicate names, or disappears after an update, clear source information narrows the search immediately. Manually added test servers should also have their own group so an update cannot make their origin ambiguous.

Keep group names stable; server remarks can change. Putting region, purpose, and protocol into every group name makes menus and filters increasingly unwieldy. A better approach is to use the group for the source and the server remark for node characteristics. For example, record the provider in the group and keep remarks in a fixed order such as “region | route | protocol.” Consistent remarks make keyword filtering useful and make it easier to identify the same batch before and after an update.

Start with an inclusion filter, then add exclusions

Server filtering usually uses two kinds of logic: keep items matching certain keywords, or remove items matching them. Start with one clear inclusion term, such as a region or purpose marker, confirm that the results are correct, and only then add exclusion terms. Complex regular expressions may be compact, but they are costly to maintain; if the provider changes its naming scheme, an existing expression may filter out every server. If the result is empty, temporarily clear the conditions and update the group to confirm that the source data exists, then restore the conditions one by one.

If you use regular expressions, watch for case, spaces, full-width punctuation, and parentheses. Hyphens that look identical in subscription remarks may actually be different characters. Safer expressions target stable words rather than decorative punctuation. The example below keeps items containing “Tokyo” or “Seoul” while excluding items marked “test” or “expired.” Whether the client provides separate inclusion and exclusion fields depends on its interface; fill them separately rather than combining both logic branches into one difficult-to-read expression.

Include:
Tokyo|Seoul

Exclude:
test|expired

Understand the difference between updating, overwriting, and deleting

When a subscription is updated, the client rereads its contents and refreshes the servers belonging to it. If a server disappears, the upstream source may have removed it, the filter may have changed, the wrong group may be selected, or subscription parsing may have failed. Do not immediately add a server with the same name by hand. First open the update log, confirm that the subscription request succeeded, and inspect the unfiltered raw results. If a manual server and a subscription server share the same remark, do not assume they are the same entry based on the name alone; compare the address, port, protocol, and group.

Before changing a subscription URL, confirm whether you are editing an existing group or creating a new one. Overwriting the old group with a new URL can mix historical and current sources under one name. When the source changes substantially, creating a new group, testing it, and then disabling the old group is usually easier to roll back than overwriting it in place. Before deleting the old group, check whether the active server belongs to it and whether routing rules or custom configurations reference its tags.

For a complete workflow for organizing multiple sources, continue with Managing multiple proxy subscriptions: v2rayN server filtering and remark practices. Once filtering is stable, move on to routing in the next chapter; do not use filtering as a substitute for routing. Filtering determines which servers appear in the list, while routing determines which outbound handles each request. They operate at entirely different layers.

Routing rules in practice: from match order to outbound tags

Rules form an ordered decision chain

The routing system selects an outbound based on information carried by a request. Common conditions include the domain, destination IP, destination port, network type, and process name. The important factor is not the number of rules but their order: specific rules should come before general ones, followed by a catch-all rule for the remaining traffic. If “proxy all domains” appears before “connect to internal domains directly,” the latter will usually never run. When adjusting rules, choose a real request from the log and evaluate it line by line instead of guessing from the visual layout.

Domain rules are suited to expressing site ownership, IP rules to handling known ranges, and port rules to restricting specific services. Process rules depend on whether the client and operating system can obtain process information, so they must be revalidated when moving across platforms. A request may enter the core as a domain and later resolve to an IP; whether the domain is retained depends on the entry point, sniffing, and DNS settings. As a result, the same domain rule may behave differently under a regular system proxy and TUN mode.

Define outbounds first, then reference their tags in routing

Underlying configurations commonly connect routing and outbounds with tags. For example, proxy identifies the current proxy outbound, direct a direct connection, and block a blocked connection. A tag is only an internal reference name; it does not create the capability automatically. If a routing rule references a nonexistent tag, the core may refuse to start or report an error while generating the configuration. When using v2rayN’s graphical routing editor, the interface handles some relationships; when importing custom JSON, you must keep the tags consistent yourself.

{
  "outbounds": [
    {
      "protocol": "freedom",
      "tag": "direct"
    },
    {
      "protocol": "blackhole",
      "tag": "block"
    }
  ],
  "routing": {
    "domainStrategy": "IPIfNonMatch",
    "rules": [
      {
        "type": "field",
        "ip": [
          "geoip:private"
        ],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "domain": [
          "domain:intranet.example"
        ],
        "outboundTag": "direct"
      },
      {
        "type": "field",
        "network": "tcp,udp",
        "outboundTag": "proxy"
      }
    ]
  }
}

The structure above illustrates the relationship between rules, but the proxy outbound must be generated by the client from the current server, so this fragment cannot be saved as a complete runnable configuration by itself. Put private-address rules first to keep local devices from being sent to a remote service; match explicit domain rules next; use the final rule to capture remaining TCP and UDP traffic. If only some traffic should use the proxy, do not add a catch-all rule. Create proxy rules for the intended domains and leave the default outbound as direct.

Choose the right domain strategy

AsIs tends to use the domain information entering the router directly and does not resolve it proactively for IP rules; IPIfNonMatch resolves the IP when no domain rule matches and then tries IP rules; IPOnDemand resolves more aggressively for requests that may require an IP-based decision. The more aggressive the strategy, the greater DNS influences routing results. If your rules are mainly domain-based, start with an option that preserves domain information; if you rely on geographic IP data, consider resolving after a domain miss.

Do not stack large numbers of domain and IP rules merely to “improve match rates.” Resolution results change, and content delivery services may share addresses. Overly broad IP ranges can affect unrelated sites. IP rules are a good fit for fixed private network ranges; for public sites, prefer domain categories and confirm them in the logs. When a rule does not match, check whether the log shows a full domain, a subdomain, or only an IP. If it shows only an IP, return to the DNS and sniffing layers instead of adding more domain entries.

Verify routing results, not just whether a page opens

A page opening does not prove that routing is correct; it may have succeeded by chance through the wrong outbound. During verification, inspect the connection log for the target, matched rule, and final outbound tag. Send separate requests to samples expected to go direct and through the proxy, and confirm that they take different paths. For LAN services, test both the hostname and the IP address: the hostname may resolve to a private address, while entering the IP directly skips the domain stage.

When a rule fails, check four things in order: rule order, condition format, information visible in the request, and the outbound tag. Temporarily move the target rule to the top. If it still does not match, narrow the condition to one domain or IP; then check whether the entry point carries the required information; finally, confirm that the tag exists. This reduces a complex rule to a verifiable minimal case. For the relationship between terms such as VLESS, VMess, and REALITY and routing, see the Glossary; protocol names themselves should not be treated as substitutes for routing results.

DNS configuration: make it clear who resolves and where

Map the resolution path first

The most common cause of DNS problems is having “multiple resolvers active at once.” An application may resolve domains independently, the operating system has its own resolver, a browser may enable separate secure DNS, the v2rayN core can handle DNS, and TUN mode may intercept system queries. Before configuring anything, answer three questions: who initiates the query, which server receives it, and whether the query itself goes direct or through the proxy. Changing only the DNS address without confirming the path often produces logs that look normal while requests still use an old cache.

Under a regular system proxy, many applications resolve domains locally first and send the IP to the proxy; others use SOCKS remote-resolution semantics to pass the domain to the core. TUN mode makes unified interception of system traffic more likely, but browser-internal resolution may still bypass the intended path. During troubleshooting, disable independent application-level DNS for comparison, clear the system cache, send a request for a previously unused subdomain, and check whether the corresponding query appears in the client log.

Divide responsibilities between local and remote DNS

A stable strategy usually does not send every domain to one resolver; it assigns resolvers by purpose. LAN hostnames and internal domains should go to a local resolver that understands them. Public domains that should be resolved from the proxy side can use a DNS service reached through the proxy, while ordinary direct domains use the system or a specified local DNS. Before split routing, preserve a direct path for private addresses and internal suffixes, or printers, router admin pages, and development services may fail to resolve.

The address format of a DNS server also affects bootstrapping. With an encrypted DNS endpoint written as a domain, the client must first resolve that endpoint, creating a “resolver bootstrap” problem. Provide a working bootstrap DNS or use an explicit IP endpoint with the server name handled correctly. Do not configure two mutually dependent resolvers in a loop: A resolves B’s domain and B resolves A’s. This usually appears as a long wait after startup or periodic timeouts.

{
  "dns": {
    "hosts": {
      "router.internal": "192.168.1.1"
    },
    "servers": [
      {
        "address": "192.168.1.1",
        "domains": [
          "domain:internal"
        ],
        "skipFallback": true
      },
      "1.1.1.1"
    ],
    "queryStrategy": "UseIP"
  }
}

This example demonstrates static host mapping, a resolver dedicated to internal domains, and a fallback resolver. In practice, replace 192.168.1.1 with a working DNS address on the local network and confirm that it answers queries. skipFallback prevents a match from falling through to other servers, which suits internal domains; if the dedicated resolver is unstable, this setting will expose the failure directly, so test it separately first.

Understand query strategies and address families

DNS may return IPv4, IPv6, or both, after which the application chooses one to connect. When IPv6 support is only partial, receiving an IPv6 address does not mean the path works; a common symptom is a delay on the first connection before falling back to IPv4. First check whether the system has a complete IPv6 route, then choose the query strategy. Do not permanently disable an address family because one connection was slow; use system networking tools to verify the default route, DNS response, and reachability of the target.

Strategies such as UseIP, UseIPv4, and UseIPv6 control which result types the core accepts or prefers; the exact supported range depends on the current core. When moving a configuration between devices, do not copy address-family settings blindly: wired desktops, Wi-Fi networks, and mobile hotspots may have different capabilities. A setting that works on a fixed network can produce successful resolution but failed connections elsewhere.

After making changes, clear the client cache, system cache, and application cache in that order, then test a new domain. Refreshing a page alone may reuse an existing browser connection and fail to show the DNS change. The goal of DNS tuning is a clear, observable path, not an ever-growing list of resolvers. Two or three clearly assigned resolution paths are usually easier to maintain than a long chain of automatic fallback addresses.

TUN mode: intercept system traffic without hiding the boundaries

TUN and the system proxy solve different problems

A system proxy depends on applications actively reading proxy settings. Browsers and most desktop applications support this, but some command-line tools, games, and custom networking components may ignore it. TUN mode uses a virtual network interface and system routes to send more IP traffic into the core, giving broader coverage while adding new variables such as routing tables, DNS interception, permissions, and virtual-interface drivers. It is not a “stronger switch” for the system proxy, but a different entry path.

Before enabling TUN, confirm that the same server connects reliably in regular proxy mode. This temporarily removes remote protocol, subscription parameters, and server reachability from the troubleshooting scope. Then record the current system DNS, default gateway, and client routing mode, disable network tools that may create other virtual interfaces, and enable TUN. For the first test, keep only basic routing enabled; do not also turn on FakeDNS and complex custom rules.

Permissions, virtual interfaces, and routing tables

Creating a virtual interface and writing system routes usually require elevated privileges. With insufficient permissions, the interface switch may change while the log reports that interface creation or route installation failed. On Windows, focus on virtual-interface status, the firewall, and route priority; on macOS, check system authorization, network-extension status, and DNS service order; on Linux, check TUN device permissions, policy routing, network-management services, and firewall rules. When something fails, start with the first system-call error in the log instead of repeatedly clicking the switch.

After the virtual interface is created, check whether the expected address and routes were added. An unchanged default route does not necessarily mean failure: some implementations use more-specific routes or policy routing. Conversely, a new default route does not prove that all traffic can return correctly. Confirm that private ranges, the current gateway, and DNS servers have not been mistakenly sent through the proxy to form a loop. If LAN access stops working, first check that private addresses go direct and that settings such as “allow LAN connections” agree with the local firewall.

MTU and UDP boundaries

When a TUN connection succeeds but some sites stall, consider the MTU. Extra encapsulation makes packets larger, and if the underlying network cannot fragment them correctly or return path-MTU feedback, larger requests may be silently dropped. Typical symptoms include small pages or text requests working while uploads, images, and long-lived connections fail. Adjust the MTU in small steps and test the same request after each change; do not reduce it drastically, since an overly small value increases fragmentation and processing overhead.

UDP also needs separate verification. DNS commonly uses UDP, but some applications use other UDP protocols as well. The server outbound, core, TUN stack, and routing rules must all permit the relevant traffic. If TCP works but UDP does not, first confirm in the routing log that UDP requests enter the core, then check outbound support and the local firewall. Do not attribute every UDP failure to DNS, since DNS can also use TCP or encrypted transport.

Restore system state after leaving TUN

When the client closes normally, it should remove the virtual interface, routes, and DNS settings. A forced shutdown, client crash, or permission change may leave stale state behind. If the network remains abnormal after TUN is disabled, fully exit the client, check whether the virtual interface and routes still exist, and reconnect to the current network. If necessary, restart the system networking service rather than deleting unfamiliar system interfaces. Removing the wrong interface can disrupt normal networking.

Stability testing should cover startup, shutdown, sleep and resume, network switching, and system restart. One successful connection proves only that the current state works, not that lifecycle handling is complete. Once all these scenarios recover correctly, move on to FakeDNS. If only browsers and ordinary desktop software need proxy access, the system proxy costs less to maintain; TUN’s added complexity pays off only when programs actually ignore proxy settings.

FakeDNS: address mapping that preserves domain information

Understand what “fake addresses” are for

Some applications resolve DNS locally first and pass only the destination IP to TUN. Once the core receives a plain IP, domain-based routing can no longer tell which site the request originally targeted. FakeDNS assigns the domain a temporary address from a dedicated pool; when the application connects to that address, the core uses the mapping to recover the original domain. This lets TUN continue handling IP traffic while domain rules remain usable.

A dedicated address does not represent a real remote host; it is meaningful only inside the local proxy chain. FakeDNS therefore must work together with an entry point, DNS, and routing that understand the mapping. Configuring an address pool alone does nothing if system queries never enter FakeDNS. The system may receive a fake address, but if traffic does not enter the corresponding TUN, the connection fails immediately. Configuration must close the loop from “DNS returns a fake address” to “the core restores the original domain.”

Keep the address pool away from existing networks

The FakeDNS address pool must be isolated from the local LAN, corporate networks, container networks, and ranges used by other virtual interfaces. If the pool overlaps a real route, the operating system may send the connection through the wrong interface and the core may never see it. Check the current routing table before choosing a pool, and consider the networks to which the device commonly connects. A pool that works at home may conflict after switching to an office network.

The size of the address pool determines how many mappings can be retained. Ordinary desktop use does not require an enormous range; avoiding conflicts and maintaining stability matter more than capacity. Mappings have a lifecycle, and inconsistent application, core, and system DNS cache lifetimes can leave an old fake address without its original domain. After changing the pool or switching FakeDNS modes, clear system and application DNS caches and establish new connections.

{
  "fakedns": [
    {
      "ipPool": "198.18.0.0/15",
      "poolSize": 65535
    }
  ],
  "inbounds": [
    {
      "tag": "tun-in",
      "protocol": "dokodemo-door",
      "settings": {
        "network": "tcp,udp",
        "followRedirect": true
      },
      "sniffing": {
        "enabled": true,
        "destOverride": [
          "http",
          "tls",
          "fakedns"
        ]
      }
    }
  ]
}

This fragment illustrates the relationship between the FakeDNS address pool and entry-point sniffing; it is not a complete standalone configuration. v2rayN usually generates the entry point and routing from the interface options. When merging configuration manually, check for duplicate inbound definitions with the same name. destOverride lets the core restore the destination from recognizable information, but sniffing does not decrypt content; it uses only protocol information visible during connection setup. Unrecognized traffic still depends on the FakeDNS mapping or IP rules.

Which requests should not use FakeDNS

LAN hostnames, internal service-discovery domains, and queries that must return real addresses to other devices generally should not use FakeDNS. Send them to the local DNS and route their private addresses directly. If printer, storage, or development-environment domains are mapped to fake addresses, the application may send the request into the core, but LAN discovery, certificate validation, or access through bypass devices may fail. Create explicit DNS split-routing rules for internal suffixes and place them before public resolution rules.

Tools that display resolution results directly to users or pass them to other programs also require care. Seeing a dedicated address in a command-line query is expected, but a later program that does not pass through TUN cannot use it. Troubleshooting scripts, monitoring tools, and containers often create the situation where “resolution happens on the host but connection happens in another network namespace.” Confirming that the query and connection use the same proxy entry point is key to deciding whether FakeDNS is appropriate.

Troubleshoot mapping failures as a closed loop

Use a fixed four-step order: confirm that the DNS query enters the client; confirm that the returned address falls within the configured pool; confirm that the application’s connection to that address enters TUN; finally, confirm that the log restores the original domain and matches the correct route. If step one fails, inspect system or application DNS; if step two fails, inspect FakeDNS rules and caches; if step three fails, inspect the virtual interface and routes; if step four fails, inspect mapping lifetime, sniffing, and rule order.

If only a few programs behave abnormally after FakeDNS is enabled, do not immediately enlarge the pool. Compare the abnormal and normal programs’ DNS behavior, and check for independent resolution, cached old addresses, bypassed system routes, or resolution results passed to another process. FakeDNS addresses the loss of domain information before TUN; it does not repair every DNS problem. Enable it only after regular DNS and TUN are stable so its specific effects remain observable.

Managing multiple subscriptions: updates, migration, and failure isolation

Treat subscriptions as configuration sources

As the number of subscriptions grows, the focus shifts from “finding the fastest server” to “controlling configuration changes.” Each subscription is an external source that changes over time: servers may be added, removed, renamed, or have their parameters adjusted. Record the source’s purpose, update method, most recent successful update, and whether it currently participates in daily selection. Group names describe the source, remark prefixes describe server characteristics, and filters narrow the view; keep these three layers separate.

A useful classification is regular, backup, and test, without building a complicated hierarchy. Regular sources are updated for daily use, backup sources retain a small set of verification samples, and test sources are used to observe new configurations. Put a new subscription in a test group first. After validating parsing, connectivity, DNS, and routing, move it into the regular list. This prevents abnormal parameters in a new source from immediately replacing the working path.

Make the update process observable

Updating every subscription at once is convenient but makes failures harder to locate. During initial organization, update each group manually and record whether it succeeded, whether the server count changed noticeably, and whether results remain after filtering. Once stable, switch to batch updates. If one group fails, do not retry repeatedly at high frequency; first determine whether the problem is a response error, a parsing error, or an empty filtered result. A successful network request only proves that content was retrieved, not that the client parsed it correctly.

Keep one verified active server before updating, and do not clean up old entries immediately afterward. Select one item from the new results and test its connection and routing before deleting clearly invalid data. If an update replaces an entire group, export the client configuration before a major change. A backup is valuable because it preserves group, remark, and rule relationships, not merely subscription URLs.

Handle duplicate servers and remark drift

Two sources may provide servers with identical parameters but different remarks, or identical remarks pointing to different parameters. Do not deduplicate by name alone. Compare at least the protocol, address, port, transport, security-layer parameters, and key identifiers. If the parameters are identical, keep the entry from the more stable source with clearer naming; if only some parameters match, treat them as different configurations and do not merge them.

Remark drift breaks keyword filters. The solution is not to keep expanding the regular expression, but to create consistent local remarks for important servers or make filters depend only on relatively stable region and purpose fields. If the client resets remarks during updates, design a looser filter and narrow the scope through groups. The more a filter depends on upstream formatting, the more often it needs maintenance.

Restore configurations by layer when moving between devices

Do not copy every system-dependent setting at once when moving between devices. First install a client that matches the platform: use v2rayN on desktop platforms, and choose v2rayNG or v2flyNG on Android according to the core requirements. Then import subscriptions and groups, verify a regular proxy connection, migrate routing and DNS, and configure TUN last according to the new system’s capabilities. Virtual-interface permissions, DNS services, and process rules vary by platform and should not be copied blindly from the old device.

For the first migration test, use one subscription, one server, and one simple routing set. Once stable, restore filters and multi-source updates. If an exported custom configuration contains absolute file paths, local ports, or LAN DNS addresses, replace them one by one. Pay particular attention to the 127.0.0.1 listening port: another program may already occupy it on the new device, preventing the core from starting.

Isolate failures instead of deleting entries repeatedly

When a server behaves abnormally, move it first to a disabled or test group and retain its logs and parameters for comparison. Immediate deletion removes the comparison sample and the entry may reappear at the next subscription update. Clean up only after confirming that the source removed it, its parameters have remained invalid, or a duplicate has been replaced. If an entire subscription becomes abnormal after an update, temporarily disable the group instead of allowing it to participate in automatic selection.

For long-term maintenance, use a short fixed cycle: update subscriptions, inspect failure logs, verify commonly used servers, remove obsolete filter terms, and back up the configuration. There is no need to repeat every step daily, but do so before each major change. Keep client updates separate from subscription-content updates. Before changing the client package, check the platform notes on the Downloads page, confirm the platform and client model, and restore the configuration from the baseline.

Custom outbounds: connect local services with an explicit fallback path

When a custom outbound is useful

Routine use generally needs only the proxy outbound generated from the current server, direct, and block. A custom outbound is appropriate for a defined engineering need, such as sending specific traffic to another local SOCKS service, assigning a dedicated exit to a class of targets, or creating a controlled fallback chain. It should not be used to hide subscription errors. If the current server cannot connect, fix protocol parameters and reachability first, then consider adding an outbound.

When designing a custom outbound, write down three things first: which rule matches the incoming request, which protocol and address the target outbound uses, and whether failure permits a fallback. Give every outbound a unique, meaningful tag, such as local-socks or direct. Avoid vague names like proxy1 and proxy2; once the configuration grows, they make the actual path difficult to identify from the logs.

Connect to a local SOCKS outbound

The example below sends traffic matching domain:service.example to the SOCKS service on 127.0.0.1:1081. That local service must already be running and must not send traffic back to v2rayN’s current entry point, or a loop will form. Using a loopback address limits the listening scope; if access to a LAN service is genuinely required, evaluate the firewall and access controls separately.

{
  "outbounds": [
    {
      "tag": "local-socks",
      "protocol": "socks",
      "settings": {
        "servers": [
          {
            "address": "127.0.0.1",
            "port": 1081
          }
        ]
      }
    },
    {
      "tag": "direct",
      "protocol": "freedom"
    }
  ],
  "routing": {
    "rules": [
      {
        "type": "field",
        "domain": [
          "domain:service.example"
        ],
        "outboundTag": "local-socks"
      },
      {
        "type": "field",
        "ip": [
          "geoip:private"
        ],
        "outboundTag": "direct"
      }
    ]
  }
}

Before saving, check the JSON structure, port type, and tag spelling. The port must be a number, not a quoted string. If v2rayN uses configuration-fragment merging, also confirm where the fragment is inserted: replacing the complete outbounds array in the client-generated configuration may remove the proxy outbound for the current server. The safer approach is to use the client’s supported custom-outbound or advanced-configuration entry point, then confirm in the generated runtime configuration that the original outbound still exists.

Avoid loops and duplicate proxying

A loop usually occurs when two local services keep handing traffic to each other. For example, v2rayN listens on 127.0.0.1:10808, a custom outbound connects to another local service, and that service points its upstream back to 127.0.0.1:10808. The log will quickly show repeated connections, port exhaustion, or timeouts. Draw a one-way path from the application to the final network exit and confirm that no step returns to the upstream entry point.

The system proxy and environment variables can also create hidden loops. If a local upstream program automatically reads the system proxy, its outbound connection may enter v2rayN again. When running a local upstream, explicitly determine whether it ignores the system proxy, or configure a direct rule for its process. Process-rule support varies by platform, so keep direct rules for target addresses as a supplement, while remembering that changing addresses requires maintenance.

Fallback is not automatic fault tolerance

Having multiple outbounds side by side does not mean the core automatically switches to the next one after a failure. Fallback, load balancing, and health checks require the corresponding policy objects and observable conditions. Unless this is explicitly configured, treat each route as a deterministic choice: after a match, traffic goes to the specified outbound. For clearer troubleshooting, configure one custom outbound at first and add policies only after it is stable.

A fallback path must also distinguish a connection failure from a failed business response. The core can usually observe whether a network connection was established, but it cannot classify every application-layer status as a reason to switch routes. Overly aggressive fallback may send the same request repeatedly, which is unsuitable for operations that submit data. Design the policy according to the protocol and business action instead of treating every failure as retryable.

From startup logs to a single-request test

After saving custom configuration, restart the core and inspect the configuration-loading stage. If you see an unknown field, missing tag, invalid port format, or array replacement, fix the first error. Once the core starts successfully, send one target request and confirm that the log shows the target domain, matched rule, and local-socks tag. Then stop the local SOCKS service and send the request again, checking whether the error clearly points to the local port. This reverse test proves that traffic actually used the custom outbound.

If the core exits immediately after you click Start, see Find configuration errors line by line in the logs. If the browser and terminal behave differently with the system proxy enabled, read Troubleshoot browser and terminal paths separately. After completing the custom outbound, save another working configuration copy and record the required local ports and service startup order. This makes it quick to restore a clear baseline after a system restart, client migration, or port conflict.