Shadowrocket Troubleshooting
Connection, Subscription & DNS Checks

01 · Connection not established

The connection toggle won’t turn on: check permissions and connection state

First, distinguish between a toggle that does nothing, one that immediately switches back off, and one that connects before disconnecting. The first two are more likely to involve device permissions or configuration; the third may also involve network changes or On Demand triggers. Don’t keep changing server passwords before a system connection is established—the remote settings may not be involved in the failure yet. Note the exact alert, when it occurred, and the toggle’s state, then check whether the corresponding connection appears in system settings.

First-time authorization and existing connection entries

The first time you turn it on, the system may ask to allow a VPN configuration and authenticate your device. This grants Shadowrocket permission to manage network traffic on this device; it is not a subscription sign-in. Confirm that the request appeared after you opened Shadowrocket, then follow the system prompt. If you cancelled, return to the app and try again. If the device is managed by a school or employer, restrictions may come from its management policy. Don’t try to bypass them by changing subscription settings; ask the device administrator whether this type of network configuration is allowed.

If the toggle immediately switches back off despite authorization, first stop any other VPN connection that is currently managing network traffic, then test Shadowrocket again. Multiple configurations in the system list do not mean they are all active or need to be deleted. Identify the active entry and its source, and only remove entries you can identify as both unnecessary and faulty. Before deleting a system connection entry, keep your in-app configuration. To create a new one, start authorization from the app; don’t install configuration profiles from unknown sources.

Check the selected item, not just the list

In Home, make sure you have selected one of your own valid server entries. Several names in the list do not mean the correct one is selected. Then open Config and check which configuration file is actually enabled. If a problem started after importing a file, restore a copy that previously worked and compare the new policy names, references, and syntax rather than clearing all rules. If the app reports a parsing error, keep the lines around the error and check for extra punctuation or incomplete sections.

If the toggle turns itself back on after you switch it off, check whether On Demand is still triggering. To isolate the trigger, temporarily disable the relevant On Demand conditions and turn the connection on manually. This is a diagnostic step, not a recommendation to disable it permanently. If the manual connection stays stable, check each network type and matching condition as you restore On Demand settings. Also check automatic connection conditions for other configurations in system settings; otherwise, an automatic reconnect can look like a faulty toggle.

When to restart or rebuild a connection

If the checks above don’t resolve the startup issue, quit the app normally, restart the device, and test again on a stable network. A restart may clear temporary state, but it won’t fix invalid configuration syntax. If you need to rebuild the system connection entry, first make sure you can restore your subscription, standalone server entries, and current Config. Don’t make deleting the app your first step: standalone entries saved on the device may not be recoverable from a subscription, and a QR code in a photo may no longer work.

Note whether the toggle switches back off after a network change, screen lock, or system alert. If the same action triggers it each time, investigate that trigger. If it happens only with one configuration, keep a working copy for comparison. This section is complete when the system connection can be established and stays up—not when a webpage necessarily opens. If the toggle is stable but requests still fail, continue to the next section instead of repeating authorization steps.

02 · Connected, but no internet

No internet after connecting: isolate the network, routing, and destination

A connected status means traffic management is active on this device. It does not confirm that the selected server can reach the destination or that DNS, rules, and the destination service are all working. Disconnect and try a page that normally works on your regular network; confirm that Wi-Fi has completed any sign-in and that cellular data is available. If access still fails while disconnected, first troubleshoot the router, signal, or network authentication. Changing proxy settings at this point would mix up basic network and client issues.

Compare the three routing modes

In Global Routing, Config, Proxy, and Direct provide three different paths for comparison. Config follows the rules in the current configuration; Proxy sends requests through the proxy path; Direct uses a direct connection. Note the original mode, then compare the same destination on the same network with the same selected server. Proxy cannot fix a server failure, and Direct is not guaranteed to work for every destination. These modes help narrow down where the failure occurs.

If Proxy works but Config doesn’t, don’t leave Proxy on indefinitely to hide a rules issue. Find the destination domain in the request log and check whether the final policy matches your expectations. Every policy referenced by a rule must exist in the configuration; similar names are not interchangeable. A webpage may also depend on multiple domains for sign-in, images, and APIs. Loading the main document successfully does not mean those dependent requests followed the same path.

Tell apart total failures and partial failures

If only one app has a problem, close and reopen it, then check whether it creates a new connection record. Some apps reuse existing connections, so refreshing immediately after changing a rule may not use the new policy. If a browser works but one app doesn’t, check the domains that app depends on, its network permissions, and the service status. Don’t assume the entire server connection is down based on one app’s error, and don’t force every request onto the same path permanently to fix a single destination.

Compare Wi-Fi and cellular once to identify differences in the local network or access network. Before switching, disconnect and make sure the new network works; then reconnect and request the same destination. If only Wi-Fi fails, check its sign-in page, router DNS, local network restrictions, and address conflicts. If only cellular fails, check the app’s cellular data permission and signal. Don’t update the subscription during this comparison, or you may change the selected entry as well.

Tie each log entry to a specific action

Record the time before testing, make one request to the destination, then inspect nearby log entries for the domain, matched rule, final policy, and failure stage. If the log shows only a DNS failure, see the DNS section. If a remote handshake has started, check the protocol settings. If the destination returns an access denial or sign-in prompt, at least some data has been transmitted; this is not a complete loss of internet access. Error text is a clue for diagnosis, not an instruction to replace every setting.

When you’re done testing, restore the original Global Routing mode and keep only changes that are genuinely needed. If you temporarily disabled a rule or automatic trigger, note why so the test state doesn’t become your everyday configuration. Still stuck? Remove sensitive details from the error summary and include the network comparison results when you check the FAQ. That’s more useful than saying only “connected but not working.”

03 · Remote connection failure

Server timeout: check the test method and protocol settings separately

A timeout means an operation didn’t finish within the allowed time. That operation might be a latency test, transport connection, protocol handshake, or request to a test destination. First identify whether the timeout came from the test result in Home or from an actual request log. If a test destination is unreachable, an entry may show as failed even while another destination works. Conversely, a test response doesn’t prove that all requests will work. Compare test results with requests to the destinations you actually use.

Check the server address and port first

Open the selected entry for editing and compare its address and port with your original server details. The address should not include a webpage path, leading or trailing spaces, or port separators. The port must match the original configuration; don’t guess based on common values. If the server uses a domain name, check that it resolves. If it uses an IP address, note whether it is IPv4 or IPv6. If the service recently changed its domain, a local cache or old connection may still use the previous address. Reconnect and check again.

If only one entry times out while other entries you already have work, the issue is more likely to be that entry’s settings or remote status. If all entries from the same source fail, check the basic network, whether the subscription has expired, and whether the remote service has changed. You can compare with another entry you already have, but don’t run repeated batch tests as a fix. Testing too often can add load and flood the logs with requests unrelated to the actual issue.

Check handshake fields as a set

The wrong protocol can prevent a handshake even when the address and port are correct. Compare the Shadowsocks encryption method and password, VMess and VLESS identity details, Trojan password, and transport-related fields against the original configuration. Don’t copy fields from one protocol into another. If you use TLS or a specific transport, also check the server name, path, and relevant header fields; a value that merely looks like a domain is not enough.

If the log reports a certificate error, first check the device’s date and time, then verify that the server name matches the configuration requirements, and finally check the server certificate status. Don’t permanently weaken verification just to make the warning disappear. If the configuration depends on UDP, the network must allow that traffic too. A transport failing on the current network doesn’t mean changing the protocol name will fix it; the server must actually support the new settings.

Choose the next step based on the failure stage

If the server domain won’t resolve, troubleshoot the local DNS path. If it resolves but the connection times out, check the access network and remote listener. If the connection is refused immediately, verify the port and service status. If a connection is established but authentication fails, check the credentials first. Log wording varies between implementations, so use surrounding entries as context rather than relying on one English word. If the error occurs on only one network, keep the comparison results.

Manually edited entries in a subscription may be overwritten on the next update. If you need a temporary comparison, copy the entry as a standalone test item and give it a clear name so you can tell whether the change was saved. Delete the test copy when it’s no longer needed and keep the correctly identified entry. A connection is working when the expected request succeeds and the log shows the expected policy—not just when a test number looks lower.

04 · Separate retrieval from parsing

Subscription failure: distinguish link retrieval, content parsing, and update overwrites

Subscription updates can fail in two different ways: the client didn’t receive a response, or it received one but couldn’t parse the content. An empty list could also be caused by a filter, a collapsed group, or names changing after an update. Keep the original subscription and working entries; don’t repeatedly delete and re-add them. Note the group state before updating, the error message, and the current network. Then run one manual update from Home and check whether the failure occurs during the network request or while importing the content.

Check that the link is complete and intended for this use

Copy the subscription link again from your own configuration provider and check for extra spaces, line breaks, or punctuation added by a messaging app. Don’t omit parameters that control access or delete content after a parameter as if it were a note. A web management address, sign-in page, and subscription URL serve different purposes; opening a webpage doesn’t mean it contains importable content. Check whether a QR code contains a subscription URL or details for a single server entry.

If the error mentions authentication, permissions, or missing content, check the original account page to see whether the link is still valid, access has changed, or a new link is needed. A new link may invalidate the old one, so check which devices will be affected before updating it. Don’t paste URLs containing access parameters into public discussions, online conversion pages, or unfamiliar diagnostic tools. When asking for help, share only the domain, error type, and parameter names; hide parameter values.

Receiving content doesn’t mean it’s in the right format

A request can succeed but return a sign-in page, access notice, or ordinary webpage instead of the expected content. Network transfer has completed in this case; the problem is the content type or permissions, not DNS resolution. If the app reports an unsupported format or unrecognized entries, first confirm that the provider’s content is intended for Shadowrocket. Distinguish a single server share, a server list, and a Config file. Each import method has a specific purpose; plain text is not automatically interchangeable.

If only some entries are missing after an update, check whether they use different protocols or newer settings, then compare them with the original instructions. Renamed entries can also leave policy groups referencing old names, so entries may appear in the list but remain unavailable to rules. Check subscription content, group filters, and Config policy references separately. If you set a filter yourself, temporarily clear it to view the full list and restore it one condition at a time; don’t assume the remote service returned no content.

Check which path the update request uses

A subscription URL is a network request, and its route may depend on the current network and configuration. If the selected server has stopped working and subscription updates rely on it, you can end up unable to recover through the same path. First confirm that the basic network works, then try a known-working route while keeping a note of the original mode. Change modes temporarily only when you know the current route is blocking the request. Don’t force all subscriptions to use one route, and don’t assume that either Direct or Proxy will always retrieve the content.

After a manual update succeeds, check that all expected entries are present, the current selection still exists, and any names referenced in the configuration are still correct. If automatic updates fail, check whether the device was offline, the app had an opportunity to run, or system restrictions applied. Don’t confuse an update that never ran with a server returning empty content. Shortening the update interval usually won’t fix a permissions or format issue; it just repeats the same failed request.

If you need to rebuild a subscription, save your standalone entries and current Config first, then note what each old group is for. After importing the new subscription, test the connection with one entry, update the existing policy references, and remove duplicate groups last. A complete recovery means the expected entries appear, the right one is selected, and rules can reference it—not just that the update button stops showing an error. For the basic import steps, return to the setup guide; this section explains how to diagnose each failure.

05 · Requests complete, but performance suffers

Slow speeds and dropped connections: start with comparable test conditions

Slow speed isn’t a single metric. A long wait for a page to open, low sustained download rates, video buffering, and mid-connection drops can occur at different stages. First identify the most consistent symptom, then test a familiar, legitimate destination a few times on the same network and at roughly the same time. Don’t compare different websites, file sizes, or video resolutions directly, and don’t use a latency test alone to judge sustained transfer performance.

Break the wait into DNS, handshake, and transfer stages

If the first visit is slow but subsequent visits are normal, check DNS and new connection setup. If a page appears quickly but large downloads stay slow, check bandwidth, congestion, and destination-side limits. If the connection pauses periodically and then recovers, check for network changes, weak wireless signal, and long-connection recovery. Logs can show whether requests are being retried, but client logs can’t accurately measure the bandwidth of every segment of the remote path.

Pause unrelated high-traffic tasks on the device while testing, such as cloud sync, system downloads, and large uploads. An upload that uses all available bandwidth can slow ordinary page loads too. Keep the device in the same location and compare with another server entry you already have. Switch one entry at a time; don’t also change DNS, rules, and protocol settings. If all entries are slow, check the local access network before changing every server.

Compare wireless conditions and destination services separately

A strong-looking Wi-Fi signal doesn’t guarantee a clear channel, an unstrained router, or a healthy upstream connection. Retest near the router and, when available, compare with cellular. Reconnect after switching networks; don’t use a failed old connection to judge the new network. If only one local network is slow, check its router or network management restrictions. Don’t reset all network settings on the device without evidence that they’re the cause.

If one website is slow while similar requests work, the issue may involve its content delivery, account status, or restrictions on the current exit route. Check which policy the failed domain actually matched and whether it took a different route from the main page. Media and other resources may use different domains from the page itself. Rules can make decisions based on known request details; they can’t infer from how a page looks which resources should share a route. After changing a rule, establish a new connection before testing again.

Dropped connections, UDP, and packet size

If text pages load but certain real-time services fail, check whether they rely on UDP and whether the current protocol and network path support that traffic. Enabling a related option alone doesn’t prove the server supports it. If short requests work but larger ones stall, packet size and path characteristics may also be relevant—but don’t copy unfamiliar values as a universal fix. Record the original value before testing, change one setting at a time, and be ready to restore it.

Long connections can drop because of screen locking, wireless network changes, remote timeouts, or system resource pressure. Record the time and device activity around each drop, and check whether it occurs under the same conditions. If connections always drop after switching access points, first see whether reconnecting restores them. If they keep reconnecting while the device is idle, inspect the remote handshake and destination errors. Calling every case “slow” can hide the actual trigger.

Once things work again, keep a reproducible baseline: network type, selected entry, Global Routing mode, destination category, and observed symptom. There’s no need to run continuous tests or burn through large amounts of data. If speed is limited by the external network or destination service, client settings may not solve it. The goal is to identify what’s responsible and what configuration can change—not to promise a fixed speed or connection duration.

06 · Resolution and rule matching

DNS issues: check resolution first, then the rule path

DNS translates domain names into addresses; rules determine which policy handles a request. They’re related but separate steps. A domain that won’t resolve, an unexpected resolution result, or a request using the wrong route can all make a webpage unavailable. Find the domain and failure stage in the log for the same failed request. Then determine whether it got no address or got an address but couldn’t connect. A page working once doesn’t prove that a particular DNS address is suitable for every network.

Avoid circular dependencies in the resolution path

Check the DNS settings that are actually active in the current Config and Settings, not just the file you edited. If the DNS resolver itself uses a domain name, it needs a working initial resolution path. If its requests have to use a proxy that hasn’t connected yet, that can create a startup dependency. Keep the original configuration while checking that the resolver address and route are reachable. Don’t combine multiple DNS snippets from unknown sources; it will be hard to tell which setting overrides another.

The same domain can return multiple IPv4 or IPv6 addresses, and the network may not be able to reach all of them equally. If only some requests fail, check which address family was actually used instead of disabling a capability globally right away. Check server-domain resolution separately from destination-domain resolution: the former can prevent the proxy connection from being established at all, while the latter may affect only certain destinations. Reconnect after changing settings so an old cache doesn’t hide the result.

Understand matching with a minimal rule snippet

The rule snippet below illustrates ordering; it is not a complete configuration to replace your existing file. The policy referenced by PROXY must exist in the active configuration. Rules are checked from top to bottom, with FINAL at the end for requests that matched none of the preceding rules. Moving it earlier may prevent later rules from taking effect. The example domains illustrate syntax only; they do not recommend routes for any real service.

[Rule]
DOMAIN-SUFFIX,example.com,PROXY
GEOIP,CN,DIRECT
FINAL,PROXY

If a request matched REJECT, first confirm that this is what the configuration is meant to do. A domain rule can reject matching requests, but it can’t understand all the content on a webpage or guarantee that a resource will always use the same address. If something is blocked by mistake, narrow the scope of the specific rule rather than deleting all rules. For more on rule order and its limitations, see the REJECT rules guide, then use the log to verify which rule actually matched.

Verify recovery and caching

After changing DNS or rules, stop and reconnect, then reopen the test app to make sure it sends a new request. An app may cache addresses or reuse connections, so one refresh doesn’t prove the new settings were applied. Don’t delete the app just to clear its cache; start with less disruptive steps, such as reconnecting and reopening it. If the problem occurs only on one local network, check whether it has specific DNS requirements or internal domains.

Verify three things: resolution completes, the expected rule matches, and the destination request succeeds. If a change moves the failure from DNS resolution to the handshake, the issue isn’t fully fixed, but troubleshooting has moved forward. Keep the before-and-after configuration differences and undo changes that didn’t help; avoid accumulating DNS settings that override one another. See the glossary for common keywords and the settings guide for where to find the relevant options.

07 · Issues after a change in state

Battery drain and update issues: keep a baseline and compare changes

Battery drain and post-update problems both call for a normal baseline. The percentage in system battery stats is relative; it isn’t the actual increase in power use under equivalent conditions. An update happening before a problem doesn’t prove that it caused it. Record device usage time, screen state, network type, and background tasks, then review the last working configuration, subscription, and system changes. Don’t roll back settings, rebuild the subscription, and reset the network all at once; you’ll lose useful evidence.

Distinguish normal traffic from repeated failures

Uploads, video playback, and cloud sync all generate network activity. If Shadowrocket manages that traffic, it may also appear in system statistics. Compare similar periods of use rather than subtracting a short idle period from a full day’s stats. If the issue mainly happens with the screen off, check for connections that keep failing and retrying, overly frequent tests, or update tasks. Use the logs to confirm whether activity is actually repeating.

Temporarily disable debug-level logging and stop unnecessary continuous tests to rule out extra work, but save relevant log excerpts first. Check whether On Demand repeatedly reconnects on an unstable network, and whether the device frequently switches between Wi-Fi and cellular. Don’t permanently turn off a necessary feature just to lower its share of the battery stats. First identify which activity consistently correlates with the extra drain, then adjust its trigger conditions.

After an update, check for three types of changes

First, an app or system update may change connection state and require you to confirm authorization or reconnect. Second, subscription content may have changed, removing an entry or policy name you used before. Third, an updated Config may differ in its rules, DNS, or external references. Identify which change occurred before choosing a section to follow. If only one file is affected, restoring a saved copy is a better way to check for file-related issues than reinstalling the app.

Before updating, save the current Config, standalone server entries, and any group relationships you need, then confirm that the backup can be opened. A subscription URL is not a complete backup: standalone entries, manually added rules, and some device settings may not be included. After updating, keep the original selection, test a commonly used destination, and only then restore automatic updates or batch operations. This keeps the change set small enough to compare rather than leaving you with several layers of overwritten settings.

Before reinstalling or downloading the client again

If you need to get the client again, verify the developer name Shadow Launch Technology Limited, official icon, and app ID 932747118 on the App Store for iPhone / iPad. Check the App Store page for the current system requirements. On Mac, identify whether your device has Apple silicon or an Intel processor before choosing a package. For other platforms, use the site’s installers at /dl/ as described in the download guide. Getting the client again is not guaranteed to fix a remote connection issue, so keep local data before proceeding.

When opening the desktop or Android version for the first time, the system may block it. After verifying the source, Mac users can follow the system prompt in “Privacy & Security” and choose “Open Anyway.” For Windows SmartScreen, verify the source, select “More info,” then decide whether to choose “Run anyway.” On Android, allow installation from unknown apps only for the source you’re using, and revoke that permission afterward if you wish. On Linux, follow the instructions for your package format; AppImage files need executable permission. See the installation approval guide. Don’t bypass the warning without checking the source.

If the issue persists after reconnecting and restoring the configuration, document the differences before and after the update and the smallest steps that reproduce the problem. Include the action that triggers it, the expected and actual results, and how often it occurs—never include complete credentials. Keep a working configuration copy and add required settings back one at a time. If a setting consistently triggers the issue, stop expanding the scope of changes. This helps restore a working baseline without mistaking a temporary recovery for a complete fix.

08 · Device and network scenarios

iPad troubleshooting: check network changes, screen lock, and local network access

The aim is not to create a separate set of rules for iPad, but to identify what differs from other devices. If the same subscription works on iPhone but fails on iPad, that tells you there’s a difference to investigate; it doesn’t prove that iPad needs a different protocol. First confirm both devices use the same network, entry, Config, and Global Routing mode, then compare the request results. This prevents device and configuration differences from getting mixed up.

Switching between Wi-Fi, cellular, and hotspot

An iPad with Wi-Fi only can’t be compared in exactly the same way as a device with cellular service. A personal hotspot is a separate network path, so record it separately. After each switch, confirm that the system has a working network before reconnecting Shadowrocket. Complete any required web authentication first. If the device still shows the old network name or keeps switching connections, resolve the network stability issue before testing.

A long-lived connection may temporarily stop working after moving from a home network to an office network. The app can still show “connected” even though the old connection hasn’t migrated successfully. Disconnect, reconnect, and retry the same destination. If reconnecting fixes it, record the network change and On Demand conditions. If it still fails, return to the basic network and server reachability checks. Don’t permanently change all rules or delete the subscription because of one failure during a network switch.

Screen lock, Split View, and reused app connections

After unlocking, an app may continue using an old session or start a new connection. Check whether the problem affects only the first requests after resuming or all subsequent requests. If reopening the destination app fixes it, investigate session reuse in that app. If all apps fail at once, check the system connection status. In Split View, two apps showing the same webpage doesn’t mean they use the same request path; check the domains each app depends on separately.

Whether a long background transfer continues also depends on the destination app and the system’s background execution rules. Shadowrocket’s connection status doesn’t guarantee that the destination app can run in the background, so don’t attribute every paused download to a rule. Keep the destination app in the foreground first and confirm that the transfer works, then compare what happens when the screen is locked. Record device temperature, low-power state, and system resource pressure too, but don’t assume a setting is at fault based on those symptoms alone.

Local network access and configurations across devices

If you can’t find a printer, open a local management page, or connect to a device on your local network, disconnect and test the basic connection first. Confirm that the destination and iPad are actually on the same local network. Device discovery and direct access by address are different kinds of requests; failed discovery doesn’t mean all local connections are unavailable. Check local network permissions, the actual destination address, and the matched policy. Adjust the configuration for the network you have; don’t copy private address ranges into a file without knowing what they’re for.

After copying a configuration from another device, check that policy references and standalone entries are all present. Matching names don’t prove that the underlying settings are identical, and a working configuration file doesn’t mean the device has system authorization. A subscription update may rename entries, leaving older rules pointing to names that no longer exist. Compare what is currently active, not just the original filename. If needed, restore the same backup on both devices and run a controlled comparison.

For this section, verify three everyday actions: requests work while the device is in use, a connection can be re-established after switching to a working network, and new requests are generated after unlocking the screen. If one step still fails, note the trigger and return to the relevant section rather than making broader configuration changes. If you still can’t identify the cause, keep a redacted log summary and note the modes and network comparison. For setup basics, return to the quick-start guide; look up specific concepts in the glossary and short answers in the FAQ.