OFFICIAL MANUAL / SETTINGS
Shadowrocket Settings Reference
Start with settings scope, then review DNS, On Demand, Global Routing, connectivity tests, logs, sync and local ports.
This section of the Shadowrocket user guide is for users who have already imported their own subscription or server details and need to decide whether a setting should be changed. For your first connection, start with the Getting Started guide and follow the steps to import details, choose a mode, connect and verify. Return to the relevant section here when you have a specific settings question. The two guides serve different purposes; you do not need to change every option before your first use.
Shadowrocket is available for iPhone, iPad, Mac, Windows, Android and Linux. This guide uses common iPhone and iPad interface terms; on other platforms, follow the options actually shown, since platform-specific features may differ. The iPhone and iPad version is a one-time $2.99 purchase on the App Store; the Mac, Windows, Android and Linux versions are free. A one-time app purchase is not a subscription to a proxy service. This site does not provide, sell or recommend servers or subscriptions.
SETTINGS / SCOPE
Settings scope, initial state and recommended baseline
First, know where each setting is stored
A connection result can depend on Settings, the active Config, the selected server and the system’s network state. Preferences in Settings are not the same as directives in a configuration file, and subscription entry parameters are not global switches. For example, a server address and authentication details belong to a connection entry, rule matching belongs to the active configuration, and permission to establish a VPN connection is controlled by the system. Before troubleshooting, note which layer you are editing. This helps avoid repeated changes in the wrong place and mistaking changes after an import for the app automatically changing all settings.
“Initial state” here means the value actually shown the first time you open a setting or before you have changed it yourself; recommended values are not presented as fixed factory defaults. The current state may vary with the system, imported configuration and previously synced data. An upgrade may also retain earlier choices. If you cannot confirm a default, take a screenshot of the current value on your device and check whether the active Config defines the corresponding parameter. Similar option names alone do not prove that interface settings and configuration files follow a single, consistent override order.
Set a minimal baseline you can restore
Before making changes, save a copy of the current configuration and note Global Routing, the selected server, the connection toggle and the current network. Keep subscription links, passwords and keys somewhere secure that you control; do not include them in screenshots shared with others. Preserve any entries that already connect successfully and test new rules in a copy. If the connection already fails, keep the original state as a point of comparison. A backup should preserve the actual inputs you can restore, not just a vague memory of which options were enabled.
A useful baseline is to start with verified server details, avoid advanced parameters you do not understand, keep one easy-to-explain Config and connect manually over a stable network. First check whether system DNS resolution works. Avoid complex On Demand conditions at first, and enable only enough logging to troubleshoot. These are practical recommendations for isolating problems, not claims that every device has the same default values or that verified features should stay disabled.
| Settings layer | Typical contents | What to note before changing |
|---|---|---|
| Connection entry | Address, port, protocol and authentication parameters | Copy of the original entry and server requirements |
| Config | General、Rule、Host | Active file and rule order |
| Settings | Testing, logging and sync preferences | Current options and their on-screen descriptions |
| System | VPN permission, network and cloud account | Network type and permission status |
Change one verifiable factor at a time
Change one variable per test and define what success looks like. For example, after changing DNS, check whether the domain that failed before now resolves; do not just check whether the connection toggle is still on. Use the same target, network and server for each test, record the result, then decide whether to keep the change. If you also switch servers, change routing mode and use a different resolver, even restored access will not tell you which change helped. That makes the result hard to reproduce the next time a similar issue occurs.
Interface locations and system capabilities may differ. If an option mentioned in this guide is missing from your device, do not substitute a similarly named option or add an unverified key to the configuration. Check which platform you are using, then make sure you are viewing Settings rather than a server editor. App downloads and system permission steps are covered on the Download & Install page. Address settings only after installation is complete and the app opens normally; network parameters cannot fix an installation permission issue.
SETTINGS / DNS
DNS: resolution paths and local mappings
First determine whether the failure is in resolution or connection
DNS translates domain names into network addresses, but resolving a name does not guarantee the connection will succeed. A domain request can fail during resolution, or resolve successfully before the connection fails. Check Log for a resolution result, then review the address used for the connection, the destination port and the policy. Blaming every timeout on DNS and repeatedly changing resolvers only adds variables. Server authentication failures, an unresponsive destination and a rule selecting the wrong policy will not go away just because you change the resolver.
Distinguish three types of names: the destination domain you visit in a browser, the domain used by the proxy server itself, and the domain for a subscription link. They may use different network paths at different stages. In particular, if the server address is a domain name, it may need to be resolved before the proxy connection can be established. Do not assume that all resolution happens through the proxy after connection. If only the server’s domain fails to resolve, first check the current network and the details provided by your service provider; then investigate DNS behavior for destination websites.
Understanding dns-server and system
In a configuration, dns-server = system means to use the system’s DNS resolver. It does not specify a particular public DNS provider or guarantee that queries go to a particular server. System results can vary with Wi-Fi, cellular networks or network management policies. As a troubleshooting starting point, system DNS preserves the current network’s normal behavior. If logs show that system resolution is failing, configure a trusted resolver that is reachable on your current network and compare results for the same domain.
[General]
dns-server = system
[Host]
localhost = 127.0.0.1
This snippet illustrates a section name and parameter; it is not a complete network configuration. Before adding it to an existing Config, check for a section with the same name or duplicate keys. Appending duplicates at the end of a file can make it unclear which values take effect. If you configure another resolution method, check the address format and transport supported by the app, along with the resolver’s documentation. Do not confuse a regular domain, a full webpage URL and a DNS server address, or enter a long list of resolvers just to experiment.
The limits of Host mappings, caching and IPv6
A Host mapping explicitly assigns an address to a name; it does not fix the destination server’s certificate or change application-level authentication. In the example, localhost is a loopback name, not a proxy server address. If you added a static mapping for a domain, an old address may keep affecting access after the destination moves. Check the Host section of the active Config as part of troubleshooting. Save a copy before deleting a mapping so you do not remove an internal name you intentionally configured.
Caching can make consecutive tests appear inconsistent. The app, system and destination program may all retain earlier results. After a change, clear the relevant cache using the method available on your platform, or quit the destination program and start a fresh request before checking new logs. Repeatedly refreshing the same page is not enough to confirm a setting works. For IPv6, also confirm that the network has working IPv6 connectivity: resolving an IPv6 address and successfully connecting to it are separate conditions.
| Observed symptom | Check first | Next step |
|---|---|---|
| No resolution result | Resolver and network reachability | Try a comparison domain on the same network |
| Address resolved, but connection timed out | Policy, destination port and address family | Check the corresponding connection record |
| Only specific domains are affected | Host mappings, cache and exact-match rules | Undo the specific change |
Choose recommended values that you can explain and verify. If system resolution works, leave it as is; add custom DNS configuration only when you have a specific need. The initial value depends on the current Config and Settings on your device; it is not guaranteed to be the same across platforms. When testing, record the domain, resolution result, time and network. Hide internal domains and server details if you share the results. If resolution succeeds but access still fails, move on to the routing and logging sections instead of adding more DNS parameters.
SETTINGS / ON DEMAND
On Demand: conditional connections and manual disconnects
On Demand and rule-based routing work at different layers
On Demand triggers connection behavior based on network conditions supported by the system. Rules determine how requests are handled while connected. In other words, On Demand answers “when should a connection be established?”; rules answer “how should requests be handled once connected?” Enabling On Demand does not mean all requests go through a proxy, and disabling it does not remove rules from the configuration. During troubleshooting, check connection status and traffic policy separately. Otherwise, an automatic reconnect can look like a rule failure, or a Direct rule can look like the VPN never connected.
The conditions, interface and availability of On Demand depend on the platform. This section focuses on how it works on iPhone and iPad; it does not claim that every device has the same list of conditions. The initial state is whatever the device currently shows. Existing system VPN configurations, synced data or earlier manual changes may also affect what you see. Before setting up conditions, disable automatic triggers, verify that manual connect, disconnect and destination access work as expected, then add conditions gradually.
Define the network behavior you want first
Before changing anything, describe the intended behavior in one sentence, such as “Do not connect automatically on a specific Wi-Fi network; connect under the defined conditions when switching to another network.” Then list the networks you actually use, including home Wi-Fi, work Wi-Fi, cellular networks and networks that require a web sign-in. Configure only conditions you can identify clearly and need to distinguish. Do not treat similarly named Wi-Fi networks as the same network or consider a Wi-Fi name a trusted identity credential.
When setting conditions one at a time, save one condition and test a network switch before adding the next. Wait for the system to finish switching networks rather than repeatedly tapping the connection toggle while the signal is still settling. Record the networks before and after the switch, the connection status in the app and the system VPN status. Looking at all three is more reliable than relying on the status bar icon alone. If conditions may overlap, check their priority in the interface; do not assume they match in the same order as rules.
Why it disconnects, then reconnects
If the connection comes back shortly after you disconnect manually, first check whether On Demand conditions are still being met. The system reconnecting to satisfy a condition is different from a faulty button. Before staying disconnected for an extended period, troubleshooting another VPN or completing network sign-in, you can disable On Demand triggers, disconnect, then confirm that the system status changes. Restore the conditions afterward if needed. Repeatedly tapping the toggle can obscure the timing of the issue, since each new trigger starts another connection attempt.
Treat networks with web sign-in separately. Joining Wi-Fi does not mean you can access the internet normally; you may still need to sign in through a system prompt. Automatic connection before sign-in is complete may fail or make the sign-in page harder to find. If this happens, disable automatic triggers, complete the required network sign-in and verify regular internet access before connecting manually. Do not use DNS changes, rule edits or repeated retries as a substitute for the network’s sign-in process.
Recheck system permissions and behavior after sleep
Even after the app has system VPN permission, device management policies or other network tools may still affect it. If the system refuses to connect, check its prompt and installed VPN configurations for conflicts rather than looking for a rule exception that does not exist in the app. Restrictions on managed devices should be handled by the device administrator; do not troubleshoot by deleting unfamiliar system configurations. Do not copy desktop background-running options into On Demand on iPhone or iPad.
After setup, test at least once by locking and unlocking the device, switching between Wi-Fi and cellular, disconnecting manually and reconnecting. If the issue occurs only when the network returns, note the time and check logs from the same period to distinguish a network that was not ready, a resolution failure and a refused connection. The best long-term setup is not the one with the most conditions, but the smallest verified set with a clear purpose. To revisit the basic steps, return to the Getting Started guide and verify the manual connection workflow first.
CONFIG / GLOBAL ROUTING
How Global Routing and Config take effect
Check the current mode before interpreting rule results
The three common Global Routing modes are Config, Proxy and Direct. Config processes requests according to the active configuration and is suitable for everyday rule-based routing. Proxy provides a comparison using the proxy route; Direct provides a comparison using a direct route. These are routing choices, not server protocols or speed ratings. If access differs from what you expect, check the current mode first instead of looking only at a rule in Config and assuming the app ignored it.
| Mode | What to check | Common use |
|---|---|---|
| Config mode | Active file, policy names and rule order | Verify rule-based routing |
| Proxy mode | Selected server and proxy-route connectivity | Isolate some rule-related factors |
| Direct mode | Direct access on the current network | Establish a direct-route comparison |
Do not guess the initial mode from memory. Check the current selection on Home, especially after switching devices or restoring data. Once you have verified the server, Config with a clear configuration is a good baseline. After temporarily switching to Proxy or Direct for comparison, restore your usual mode. If the interface also offers options such as Scene, check their specific behavior separately; do not treat them as the same switch as the three-mode test described here.
Rules are matched from top to bottom
In Config mode, rules are matched in order, and the first match determines the policy for that request. More specific DOMAIN and DOMAIN-SUFFIX rules generally belong above broader fallback rules, with FINAL at the end. Policy names in rules must refer to policies that actually exist in the active configuration. PROXY below is only an example of a proxy policy to associate; copying that word does not establish a server connection. Check your configuration structure and policy names before using the example.
[Rule]
DOMAIN-SUFFIX,example.com,PROXY
DOMAIN-KEYWORD,example,PROXY
IP-CIDR,192.168.0.0/16,DIRECT
GEOIP,CN,DIRECT
FINAL,DIRECT
This example shows how domain suffix, domain keyword, address range, geographic matching and a final rule can be ordered; it is not a complete configuration for everyone. DOMAIN-SUFFIX matches the relevant domain and its subdomains. DOMAIN-KEYWORD is broader and can affect unrelated domains whose names contain the same text. IP-CIDR matches an address range, while GEOIP depends on available location data. Neither is a simple substitute for precise rules based on service domains, and neither guarantees that a service always uses the same addresses.
Test new requests after changing rules
Saving a configuration and selecting it are two different things. After editing a file, confirm that it is the active Config, then reload it or rebuild the connection as required by the interface. Existing long-lived connections may not immediately use a newly selected route. For a proper test, close the destination app’s old connection, make a new request and check the target and policy in the logs. A page that is still open does not prove the new rule matched; it may be cached or using the existing connection.
If some content in an app works and some does not, check the individual domains it requests rather than inventing a general rule based on the app’s name. Login, images, APIs and media may come from different destinations. Find the failed request in the logs, then choose a sufficiently precise matching method; do not add a broad keyword rule to fix one domain. USER-AGENT matching also has prerequisites. Do not assume that every type of traffic provides the same information for matching.
To roll back, switch to the saved Config instead of appending a conflicting rule at the bottom of the file. For an explanation of the full General, Rule and Host structure, see Configuration File Sections Explained. If Proxy mode works but Config does not, check the matched policy first. If both fail, check the server and network. This order helps distinguish rule problems from connection problems and avoids repeated changes.
TOOLS / CONNECTIVITY TEST
Reading Ping and Connectivity Test results
Each test result answers a specific question
What Ping measures depends on the test method. One method may check only whether a host or port responds; another may include a protocol handshake or a test request. Read the description of the current method before interpreting its timing or failure status. Do not treat every result as the full time required to load a webpage. A responding host does not prove authentication details are correct, and a successful proxy handshake does not prove that a specific service endpoint is available.
Connectivity Test checks reachability under specific test conditions. The test address, timeout, selected server, DNS and current network can all affect the result. The initial test method and address are whatever your device currently shows; this guide does not prescribe an unverified default URL. Keep settings you can already explain, and choose a stable test target with a simple response. If a test fails, note the error type instead of assuming a red or blank result means the server is permanently unavailable.
Consider latency, throughput and reliability separately
Latency measures the time for a round trip or operation. Throughput measures sustained transfer capacity, while reliability requires repeated observation. A low reading once does not mean downloads will be faster, and one timeout does not mean all future requests will fail. Small requests can be affected by temporary network congestion, device wake-up and cached DNS results. When comparing servers, use the same test method and target within a similar time window. Do not rank results collected under different conditions and treat the ranking as a long-term conclusion.
A timeout that is too short can mark a temporarily slow but working connection as failed; one that is too long slows troubleshooting. Start with a reasonable existing value. Adjust it only if logs show that handshakes regularly approach the timeout limit, and record the completion rate before and after. Do not use an unlimited timeout to hide persistent connection refusals or authentication errors. Keep test intervals reasonable too: frequent, back-to-back tests can affect device and network load, and may trigger server-side limits that distort later results.
| Test symptom | What it may indicate | What it does not prove |
|---|---|---|
| Host responds | The probe path is reachable | Proxy authentication and destination access work |
| Handshake failed | An issue in the protocol or connection stage | That DNS is definitely at fault |
| Test request succeeded | That target was reachable at the time | All websites and apps work normally |
| Occasional timeout | A transient failure occurred | The server is permanently unavailable |
Break testing into stages you can diagnose
First check that the current network works. Then confirm that the address, port and protocol in the subscription entry match the details from your service provider. Next check whether the server domain resolves, whether a connection can be established and whether authentication succeeds. Only then test the destination request. Use the relevant records to confirm each stage; do not skip authentication and change routing rules instead. For protocols requiring additional transport or security parameters, check each one against the server’s requirements rather than copying values from another entry.
If a test succeeds but an app will not open, check requests made by the app itself. The test target may use a different rule, or it may be a lightweight endpoint while the app needs several domains. Check Global Routing and the matched policy, then look for the failed destination in Log. Conversely, a test address may be unreachable while the actual service still works. In that case, change the test target rather than deleting server details you have already verified.
If all entries fail at once, check shared factors first: the current network, system VPN permission, test target and DNS. If only one entry fails, check its details and the server status. Reordering the list does not fix the problem, and repeatedly updating a subscription while results fluctuate can erase useful evidence. For concise answers to common errors, see FAQ. The logging section here explains how to match test results to specific connection activity.
SETTINGS / LOG AND DATA
Log and Data: find requests without piling up records
Set the right logging scope before reproducing the issue
Log is useful for placing a failure in its timeline, not for collecting as much data as possible. Before enabling it, write down the question you need to answer, such as “Did the domain resolve?”, “Which rule matched?” or “At what stage did the handshake fail?” Available log levels can vary by platform and interface; use the default shown in your current settings as the reference. Use the lowest level that answers the question, and temporarily increase detail only if regular logs are insufficient. Restore your usual setting when troubleshooting is complete.
Before reproducing the issue, note the time, network type, Global Routing mode, Config name and local label for the selected server. If the logs are already cluttered, clear them only after confirming you do not need to keep them, then perform one minimal action, such as opening the page that fails. Do not launch several apps, run a speed test and update a subscription at the same time; their many requests will overlap and make it hard to identify a failure at a particular moment. If the device clock is inaccurate, correct it before comparing records.
Read logs in order: resolution, policy, connection
Start by finding the target domain or address. Check for a resolution result, confirm the policy that was applied, then review the connection and authentication results. If the target does not appear in the logs at all, the request may never have been made, the destination program may be using a cache, or the current logging scope may not include it. Do not immediately conclude that the client dropped the request. Quit the destination program, rebuild the connection, reproduce the issue and check that the system VPN status matches the app’s connection toggle.
For a timeout, determine whether it occurred during resolution, connection setup or while waiting for the destination to respond. For a refused connection, check the destination port and server listener. For an authentication or security handshake error, check protocol parameters, system time and server requirements. Similar error messages do not necessarily have the same cause. Do not lower security checks just to remove a warning, and do not send records containing the full authentication context. Extract only the smallest relevant section that identifies the failure stage.
What Data statistics mean—and their limits
Data traffic statistics can help show whether transfers are occurring, but they cannot by themselves prove that a service completed successfully. Connection setup, retries, background refreshes and protocol overhead can all generate traffic. Check the scope described by the interface; an in-app counter is not necessarily an ISP bill, and a session figure is not necessarily a total since installation. Note the time before resetting statistics and compare changes only within the same scope.
If the connection is on but Data does not increase noticeably, first confirm that the destination program made a new request, then check routing and logging scope. If Data keeps increasing while a page still fails, find the specific failed request; traffic alone does not prove that the connection is working. Background apps, system services and automatic retries can all transfer data. Close unrelated destinations and reproduce the issue once; this is usually more useful than watching a total traffic counter for a long time.
| Record details | Troubleshooting purpose | Before sharing |
|---|---|---|
| Destination domain and time | Match the record to the actual failed action | Hide internal names and query parameters |
| Policy and failure stage | Distinguish rule, resolution and connection issues | Keep only the context needed |
| Server and authentication details | Check the entered details locally | Hide addresses, passwords and keys |
| Change in Data statistics | Confirm transfers over the same time period | State the statistics’ start time and scope |
Export, retain and close the troubleshooting loop
Logs may contain destination domains, server addresses, subscription requests and device environment details. Review them locally before exporting, and hide passwords, keys, full subscription links and their query parameters. If only a few lines near an error are needed, do not send the full history. Check screenshots for server labels in the header, sidebar and share panel too. If valid credentials have already been exposed, contact your own service provider to address those credentials; deleting the image alone is not enough.
When troubleshooting is complete, record the finding in a format such as: “On this network, this setting caused a failure at this stage; undoing it did or did not restore service.” Keep necessary excerpts and verified configurations, remove sensitive exports you no longer need and restore temporary detailed logging. The next time a similar issue occurs, you can follow the same diagnostic path rather than trying every option again. Logs have served their purpose only when the conclusion matches a reproducible result.
SETTINGS / WIDGET AND ICLOUD
Widgets, iCloud sync and restoring on a new device
A Widget is a shortcut, not a separate configuration
A Widget provides status or shortcuts where the system allows them. The available sizes, buttons and refresh behavior depend on what your device offers. It is not a separate server setup or a full monitoring screen that continuously updates in the background. First complete the connection setup in the app, then add a Widget using the system’s available options. If your system does not offer a relevant Widget, do not follow desktop widget instructions from another platform.
Widget updates may depend on the system’s refresh schedule. If the displayed status seems wrong, open Shadowrocket and check the actual connection status, then check the system VPN status. Do not rely on a single line of text in the Widget to decide whether the connection has dropped. After using a Widget to change the connection, wait for the system to finish before checking the result. If On Demand conditions are still met, troubleshoot the reconnection under On Demand rather than repeatedly removing and adding the Widget.
Clarify what will sync before you start
iCloud sync is a related feature for Apple devices and requires the device to allow the app to use the relevant cloud service. It is not a universal account sync feature across all platforms. The initial toggle state, syncable items and device requirements depend on what the interface shows. Before enabling sync, confirm that you are signed in to the right system account, have available storage and a working network. Being signed in does not mean app data has finished syncing, or that every local file is included automatically.
Check separately whether server entries, subscriptions, Config files and preferences appear on the other device. The appearance of any one item does not prove that the entire migration is complete. In particular, distinguish an exported configuration file from a server list: a file may restore rules without containing complete authentication details, while a subscription link may fetch entries again without restoring every local edit. List what you actually need to keep, then choose a sync or export method.
Sync is not an archive of past versions
Sync may propagate deletions and changes to other devices, so it is not a substitute for a separate recovery copy. Before reorganizing items in bulk, export important configurations and keep subscription details in a secure location you control. Editing the same content on two devices at once can cause overwrites or duplicates. Choose one device as the source for the current changes and wait until the other device has been checked before continuing. Do not alternate between renaming and deleting the same items before confirming sync status.
If the expected data does not appear in the cloud, first check the same account, the app’s cloud permissions and the network. Allow a reasonable amount of time for sync, then check each item. Do not repeatedly toggle sync, sign out of the account or clear local data to force it; these actions change the situation and may remove the only copy that has not yet uploaded. If there is a conflict, save both versions separately, compare them and keep the one you have verified rather than deciding based only on which device is newer.
What to check after switching devices
On the new device, first confirm that the app opens, then restore data and check the active Config, selected server and Global Routing mode. Matching server labels do not guarantee matching parameters; check the address, port, protocol and service provider’s requirements if needed. The first connection may require system permission; follow the system prompt. Restoring a configuration file does not replace this step. Do not delete the copy on your old device before testing successfully, and do not assume system permissions transfer like ordinary preferences.
Finish by testing a manual connection, destination access, disconnecting and switching networks. Then set up On Demand and Widget again if needed. If entries are duplicated, check whether they came from a manual import or a subscription update before deleting them; otherwise they may reappear. For the full process, see Backing Up and Migrating to a New Device. Keep a separate, verified configuration copy and note what types of information you will need to restore instead of relying only on a cloud list that looks complete.
SETTINGS / LOCAL PROXY
Proxy ports, local network access and final checks
A local listening port is not a server port
Local ports related to Proxy let this device or an authorized device pass requests to the client. The port entered under Add Server is where the remote server accepts connections. They have different roles; do not change them just to make the numbers match. The remote port must match the details from your service provider, while the local listening port must match the program that needs to connect. The initial port depends on the platform and what it actually shows. This guide does not prescribe a fixed number for every system or ask users to enable a feature they do not need.
Local ports also differ by the proxy type they accept. HTTP and SOCKS5 use different connection methods, and the destination program must select the type that matches the listener. Entering a port in a field for the wrong protocol may appear to connect but fail to complete requests. Confirm the type, listening address and port before testing. Do not assume an option labeled Proxy accepts every protocol. If a local program has no proxy settings, check what it actually supports instead of inventing an adapter option in Shadowrocket.
Loopback addresses and local network addresses
A loopback address points only to the current device. Another device’s loopback address will not connect to the device running Shadowrocket. To allow local network access, use a reachable LAN address for the device running the app, and check the listening scope, system firewall and whether the network allows devices to communicate with each other. Feature availability depends on the platform’s actual options; do not assume that a desktop listening setup also applies to mobile devices.
As a rule, expose only the access scope you actually need. If only local programs will connect, keep access limited to the device. For LAN access, enable it only on a network you understand and control, and apply any available access restrictions. Do not expose a listening service directly to the public internet or disable system protection just to resolve one connection failure. Wi-Fi networks may have device isolation enabled, so two devices connected to Wi-Fi with the same name are not necessarily able to reach each other.
| Parameter type | What it must match | Common mistake |
|---|---|---|
| Remote server port | Your service provider’s configuration | Changing it to the local listening port |
| Local listening port | The proxy settings in the connecting program | The port is already in use by another program |
| Listening address | Local device or LAN access scope | Using a loopback address to connect to another device |
| Proxy type | HTTP or SOCKS5 connection method | Checking only the number and ignoring the type |
Troubleshoot by layer: local device, LAN, destination request
If a port does not work, first confirm that listening is enabled, settings are saved and no other program is using the port. Next, run a protocol-matched test from the same device and confirm that the request appears in Log. Test from another device only after local access works. If remote access fails but local access works, check the address, listening scope, firewall and network isolation first. This helps distinguish LAN reachability issues from proxy server problems and avoids changing connection entries that already work.
If a request reaches the client but still fails, check Global Routing, the matched rule, resolution result and remote connection instead of changing the local port again. A port provides an entry point; it does not guarantee success at later stages. Watch for a forwarding loop: if the system proxy points to the local listener and an upstream setting sends the request back to the same entry point, forwarding may loop or fail. Map the request path before adding a system-wide proxy, and keep the original settings so you can revert them.
Close the loop after changing settings
After making changes, verify them in this order: check the current network, confirm server details, connect manually, check DNS and rules, make a real request, then review Log and Data. Restore On Demand, Widget and sync preferences afterward if needed. Keep only changes that passed verification; undo options that did not improve the result. If only one app fails, record its destination and the failure stage instead of rewriting the entire configuration for a localized issue.
For long-term maintenance, record the purpose and verification method for each setting, not just a list of toggles: why a resolver was specified, which rule needs priority, which local program uses a listening port and what to check after migration. When a new issue arises, return to the relevant settings layer, then consult the FAQ or 10 Questions and Answers for New Users. The aim of this reference is to ensure every retained setting has a clear purpose, an observable result and a recovery path you can follow.