Shadowrocket
Subscriptions and Server Management

Know the Difference: Subscription, Server, and Config

A subscription URL retrieves a list of server records. The app can request it again later to receive additions, removals, or updated settings. A server record describes a single connection endpoint and usually includes its protocol, address, port, and authentication details. Config files contain settings and rules. These may come from the same service documentation, but they serve different purposes. Entering a Config URL as a server subscription may not produce a usable list.

Before you begin, make sure you have a complete subscription URL—not an account page, an information page, or a server sharing link. Get the subscription URL from your service provider and follow its Shadowrocket instructions to choose the right format. Don’t identify a URL by whether it ends with a familiar file extension: some subscriptions use dynamic URLs, and the response content determines what the app can parse.

Select Subscribe in Add Server

Go to Home, open Add Server, select Subscribe under Type, and enter the complete address in URL. Give the entry a recognizable name, such as its purpose or source, rather than a long note containing account details. The layout may vary by device or app state, so use the fields currently shown. Most importantly, make sure Type is set to Subscribe, not a single-server protocol.

After pasting, check the entire URL. Keep the scheme, domain, path, and any parameters after the question mark intact. Make sure there’s no Chinese full stop, quotation mark, or line break at the end. Some messaging apps wrap long URLs across lines without changing the actual text, but manually copying a wrapped URL can omit characters. Copy the original URL instead of retyping it from a screenshot.

1. Check that Type is Subscribe and URL contains the complete subscription address.
2. After saving, return to Home and confirm that the subscription or its server group appears.
3. Wait for the import to finish, then check that the servers appear under the expected subscription—not just that its name is visible.
4. Open a server record and check its fields before connecting or testing.

How to Confirm an Import Is Complete

Saving the subscription entry, requesting the subscription, parsing its contents, and creating a server list are separate steps. A saved entry only confirms that it exists locally; it doesn’t prove that remote content was retrieved. If you see a subscription name but no servers, wait for the update to finish, then check whether the response is empty or could not be parsed. Don’t add the same URL repeatedly—you’ll create duplicate entries and make it harder to tell which one is being updated.

When the list first appears, spot-check a record’s Type, Address, Port, and authentication fields against your existing details. A name is only a label, not a substitute for checking the settings. If the number of imported servers differs from what you expected, don’t assume the app lost data. A remote subscription may return different results based on account status or access scope. Check the address and account status, then ask your service provider what records that URL should return.

If the subscription loads but a server fails to connect, check its settings and test results rather than recreating the subscription. If no servers appear, check the URL, the request result, and the response format—in that order. These failures happen at different stages. Keeping them separate avoids repeatedly toggling the connection for a list that hasn’t finished importing.

This section covers adding a remote list to Shadowrocket. For when to update it, whether updates can overwrite local edits, and what to preserve when a list is empty, see Update Settings. To follow a complete connection workflow, return to the quick start tutorial.

Separate the Connection Endpoint from Its Display Name

Manual setup is useful when you have a complete set of settings and need to add a single server. From Home, open Add Server and select Type first. The fields vary by protocol, so don’t enter everything and then change the type. After switching, review authentication and transport settings again to catch cleared fields or values that now mean something different.

Address is the server hostname or IP address. Port is the connection port and must match the details you were given. Don’t enter a web page URL with a path in Address, and don’t guess the port from the end of an address. The display name is just a label; including a protocol name in it does not change Type. A correct name with the wrong type still won’t connect as expected.

Check Authentication, TLS, and Transport Separately

For Shadowsocks, check the encryption method and Password against your source details. VMess and VLESS commonly use a UUID, but their settings aren’t interchangeable just by changing Type. For Trojan, check Password and TLS settings. HTTP and SOCKS5 have different authentication requirements. Which fields appear and whether they’re required depend on the selected protocol and current interface—there is no universal set of fields for every type.

TLS, SNI, Host, and Path belong to different layers. Address determines where to connect; SNI provides the server name for the TLS connection; Host and Path may be used in requests for the selected transport. These values may use the same domain, but they don’t have to. If your source details omit a field, don’t automatically copy Address into every blank field or fill it based on another server’s settings.

For certificate errors, first check the system time, SNI, and server certificate configuration. Allow Insecure affects certificate verification and should not be enabled casually as a routine fix. A failed certificate check needs an explanation; simply hiding the error isn’t enough. For protocols such as WireGuard and Hysteria2, use the complete set of protocol-specific settings rather than trying to fit them into a simple Password or UUID mapping.

Save, Then Troubleshoot One Change at a Time

When you’re done, revisit the edit screen and check the settings—especially spaces around passwords, missing characters in a UUID, and the port. An input method may replace ordinary punctuation with full-width characters, making manual entry error-prone. Copy the original values when possible. If you find a mistake, change one field at a time and note what happens before and after, so you can tell which change made a difference.

If a sharing link for the same server imports successfully but a manually entered record fails, compare Type, authentication, TLS, and transport settings before assuming the address is invalid. Keep the original imported record as a reference rather than overwriting it. Conversely, if manual setup works but a subscription-generated record fails, check whether the subscription still contains outdated settings.

A successful save only means the fields were accepted; it doesn’t confirm that authentication or the remote service works. Select the record and run Connectivity Test, then check Global Routing and the result of an actual request. For Trojan fields, see the guide to Address, Port, Password, and SNI. Don’t treat an example for one protocol as the default for another.

Check What the QR Code Contains Before Scanning

A QR code can contain a single-server sharing link or a subscription URL. You can’t tell which from its appearance. A successful scan only means the text was recognized—not that the URL is accessible or the settings are valid. If you have a QR code, check the source instructions to determine whether it points to a subscription or a single server, then use the Scan QR Code option in Shadowrocket.

The first time you use the camera, the system may ask for permission. Grant it once you’ve confirmed the purpose. If you previously denied access, check Shadowrocket’s camera permission in system settings. Keep the whole QR code in view, without cropped edges, screen glare, or excessive image compression. Long QR codes have denser patterns, so opening the original image at a larger size is usually more helpful than repeatedly moving the camera closer.

If the QR code is displayed on your device, use the image-recognition option currently available in the app. If there isn’t one, import the original text link instead. Don’t upload a QR code to an unfamiliar website to work around a scanning issue, and don’t create a public image containing real credentials. Keep the original QR code for recovery, not as material to share publicly.

Keep Clipboard Content Complete and Limited to One Item

To import from the clipboard, copy one complete item from the original source, then return to Shadowrocket and use the clipboard import option currently shown. If the system asks you to confirm pasting, make sure it’s the item you just copied. Don’t rely on old clipboard contents: copying in another app may have replaced them, and cross-device clipboard sharing may provide different text than expected.

Copy only the link, without its title, number, code fences, or quotation marks from a message. Whether the app can recognize multiple links at once depends on their format; for your first import, add them one at a time. Check what appears in the list after each import before moving on. This makes it easier to trace duplicates or incorrect entries.

1. Return to your source and copy the original link or open the original QR code.
2. Select Scan QR Code or the clipboard import option currently available in the app.
3. On the confirmation or edit screen, identify Type and check key fields such as Address and Port.
4. After saving, confirm where the record appears, then test it. Don’t rely on the import confirmation alone.

If the app doesn’t recognize clipboard content, first identify whether it’s a subscription URL, a protocol sharing link, or ordinary text. For a complete subscription URL, go to Add Server, select Subscribe, and paste it into URL. Handle a single-server link according to its protocol; don’t change every unrecognized item to Subscribe just to make the interface accept it. The import method doesn’t eliminate the need to identify the content type.

Handle Recognition and Connection Failures Separately

If scanning does nothing, check image quality and permissions. If the app recognizes the content but reports an unsupported format, check the text structure. Only when a server has been created but won’t connect should you troubleshoot its fields and network. Describing these cases separately can greatly shorten troubleshooting. “The camera sees the code but no record appears” and “A Trojan record was created but authentication failed” require completely different checks.

If you see duplicate names after importing, don’t delete either record right away. Check whether they come from different subscriptions or use different ports or transport settings. A QR code title is usually just a label; matching titles don’t mean the settings are identical. Once you confirm a duplicate, keep the copy with a clear source and a reliable way to restore it. Then follow this page’s deletion steps rather than cleaning up unverified records in bulk.

When asking for help, share only the import method, recognized Type, stage of failure, and checks you’ve completed—not the full content. After importing, copy other non-sensitive text to replace credentials on the clipboard. If you suspect credentials have been exposed, get replacement details from your service provider; changing the local record’s name won’t help.

Protocol Prefixes Indicate How a Link Is Parsed

Single-server sharing links usually start with a protocol prefix, such as ss://, vmess://, vless://, or trojan://. The prefix indicates how the link may be parsed. The rest may contain encoded fields or an address with query parameters. The prefix only suggests the general type; it doesn’t confirm that the authentication details, TLS, and transport settings are complete.

A sharing link may contain user information, a host, a port, query parameters, and a label. The structure varies across protocols and link generators, so don’t use one protocol’s parsing method for every link. Keep the original text, let Shadowrocket parse it, and then check the visible fields on the edit screen instead of rewriting the link in a text editor.

https://example.com/sub?token=xxxx
trojan://[email protected]:443?security=tls&sni=example.com#Example

The examples above show the difference in appearance between a subscription URL and a single-server link. They contain dummy values for illustration only, not working connection details. Query parameters usually follow a question mark, and a label often follows a hash, but the exact format depends on the protocol. Percent-encoded characters matter too: replacing them with more readable text may change the actual password, path, or label.

Encoding Isn’t Encryption, and a Subscription Isn’t a Rules File

Some links or subscription responses use Base64 or other encoding to represent content. Encoding represents data; it does not keep credentials private. Treat a string you can’t read at a glance as sensitive password data. When troubleshooting, don’t paste the full content into a public decoder. First check that it was copied completely, that the response is the expected type, and that the app can parse it.

A subscription response may contain multiple server links or another supported format. When opened in a browser, it may appear as text, trigger a file download, or show a login page. None of these behaviors alone proves that the content is suitable for the current import method. If the response contains a login prompt, error message, or web page, the app may not be able to generate servers—even if the request reached the remote address.

Rules in Config are a different kind of content. The example below shows a common Shadowrocket Config structure, with rules listed under [Rule]. It contains no server authentication details and can’t replace a Subscribe URL. Apply rules to your own Config only after you understand its existing structure and have confirmed what needs to change.

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

Imported Servers and Routing Still Need to Work Together

A server record specifies which connection endpoint to use. Global Routing specifies how traffic chooses a connection. Config follows the active configuration, Proxy uses the proxy route, and Direct connects directly. If you’ve just imported a server but Global Routing is set to Direct, traffic won’t use that server; this doesn’t mean the import failed. Interpret test results in the context of the current mode, not just the selected server shown in the list.

In Config mode, rule order and the active configuration also matter. DOMAIN-SUFFIX matches domain suffixes; GEOIP checks IP location data; FINAL is the fallback when no earlier rule matches. Copying just the FINAL line doesn’t create a complete routing policy. Don’t assume an example configuration is suitable for every network.

If your source provides both a subscription and a Config file, confirm their purpose, update method, and management location separately. Updating the server list doesn’t necessarily update rules, and switching Config doesn’t necessarily replace server settings. Note both separately in your backup documentation so that if the list looks normal but traffic takes an unexpected route, you can troubleshoot the right layer.

When to Update

After the service changes server addresses, authentication details, or availability, your local list may be out of date. Update the relevant subscription to sync the remote list; updating won’t improve your current connection speed. If a request simply times out, test the existing record and network first. Don’t update all subscriptions, switch Config, and restart the connection at once—you won’t know which change affected the result.

Use the subscription management option provided by the app to update the subscription you need, then check the result for that group. If the current interface offers an update interval or automatic updates, set it as needed. Don’t assume the app always runs in the background, or that not seeing an update notice means the system has synced the list. For important changes, run an update yourself and check the result instead of relying on an estimated schedule.

Before updating, note the names and key settings of currently working servers, and save a separate backup if needed. A subscription list is maintained remotely, so updates may rename or remove servers or change their settings. Keeping older records can help with comparison, but whether they still work depends on the remote service. A backup doesn’t extend their validity.

Troubleshoot at Three Levels: Request, Parsing, and Use

If the request fails, first check whether your network is working, then look for extra spaces or a truncated URL. If the domain in the subscription URL can’t be resolved, the failure happens before the content is retrieved; repeatedly editing a server’s Password won’t fix it. Don’t delete the existing list yet. Keeping it lets you compare whether the remote address is temporarily unreachable or locally saved servers are failing too.

If parsing fails, find out what the response actually contains. An expired-account notice, access restriction, or ordinary web page may appear where the server list should be. Shadowrocket can’t generate servers from that content, but this doesn’t mean you should try a random protocol type. Check account status and the URL’s intended scope, then ask your service provider to confirm the subscription details.

If the list appears but servers won’t connect, check the individual server settings and run Connectivity Test. A successful subscription update doesn’t guarantee server availability: an endpoint may be under maintenance, or its authentication details may no longer match the remote service. Record the full symptoms—“update succeeded, record exists, test failed”—rather than simply saying “the subscription is broken.”

Avoid Repeated Updates and Overwriting Manual Fixes

Frequent repeated updates usually won’t change an incorrect response and may trigger remote access limits. After a failed update, wait for the request to finish, identify the failure stage, then retry with a clear purpose. If you switch networks to compare results, change only the network—not the URL. Changing one variable at a time helps identify whether the issue is with your local network or the remote address.

Local renames or edits to subscription-generated servers may be overwritten during the next sync. For a temporary test, copy the record as a separate entry and label its purpose. For a lasting correction, verify the remote subscription rather than repeating the same local edit after every update. Automated maintenance depends on correct source data; manual fixes can’t replace it.

After confirming the update is complete, check that the currently selected record still exists and test it again. If a server was renamed or removed, don’t rely on its old name to confirm that the same endpoint is selected. For a step-by-step checklist, see What to Check When a Subscription Update Fails or the List Is Empty. For other connection issues, see Troubleshooting.

Organize Subscriptions by How They’re Maintained

When managing multiple subscriptions, keep each source clearly identifiable. Give every subscription a distinct name so you can tell which group to update or delete and which remote list created a server. Don’t call every entry “Default” or “Favorite,” and don’t put the full subscription URL in a note—it increases the risk of exposing credentials in screenshots or day-to-day use.

Use a stable label for the purpose, such as “Daily,” “Backup,” or “Test,” and keep the mapping between each entry and its purpose in a private note. If you already have a naming convention, stick with it rather than renaming entries just to change their order. A region or purpose in a name doesn’t prove how a server behaves; check your source details and test results.

Importing the same subscription more than once may create multiple groups with similar names. Before organizing them, compare their URLs, server settings, and update status—not just the group name. Different URLs may return overlapping lists, while the same URL may return different results depending on account status. The goal is to remove unnecessary copies, not to force every similar-looking entry into one group.

Separate Subscription-Generated and Manually Added Records

Subscription-generated records follow remote changes. Manually added records are useful for separately provided settings or temporary checks. Both can coexist, but make the difference clear in their names or groups. If you copy a subscription record for troubleshooting, note that it’s a local copy and why you made it. When the original subscription updates, you’ll know the copy hasn’t been synced.

Temporary copies can easily become old records no one can explain. After troubleshooting, decide whether to keep the record, update its notes, or delete it. If you keep it, explain how it differs from the original—for example, it uses a corrected SNI or a port specified in the source details. “Works” isn’t enough: without noting the network and settings, the result may be hard to reproduce later.

If the app currently lets you view, filter, or collapse records by subscription, narrow the list to one maintenance group before making changes. Before a bulk action, confirm the filter and selected records—especially whether hidden records are included. If you’re unsure, test the action on one nonessential record first, then continue to avoid changing the entire list at once.

Selection, Sorting, and Rule References Are Different

A record’s position in the list controls its display order, not usually the active connection. After moving a server to the top, confirm which record is actually selected on Home. If Config uses policies or groups, also check which target the rules select. The first item on screen and the current routing target are different things; don’t confuse them while organizing records.

If Config refers to specific names, renaming or deleting those records may affect later selection and maintenance. Before changing names, check the related Config entries and keep a record of old and new names. If you’re unfamiliar with the Config, don’t rename records and edit rules in bulk at the same time. Organize and verify the server list first, then check the Config separately to keep any rollback manageable.

If you maintain the same records on iPhone and iPad, you can use the same group labels, but don’t assume the order, selection, or sync status is identical on both devices. Check the source and current selection on each one. After organizing, keep a short index of which items follow a subscription and which need manual maintenance. It’s more useful for recovery than a screenshot of the server list.

Understand What the Test Measures

Connectivity Test shows how a server performs under the current test conditions. What it measures depends on the test method and target selected in the app. Don’t assume that every result shown in milliseconds represents the same metric. Network routes, DNS resolution, the remote endpoint, and the test target can all affect the result. Numbers taken at different times or on different networks aren’t directly comparable.

Latency describes the time taken for a particular test stage. It doesn’t directly indicate sustained transfer speed or guarantee that every site will load. A record with a fast test may still fail on a real request due to authentication, TLS, rules, or the target site. A timeout doesn’t necessarily mean the server is permanently unavailable; check whether the test method suits your environment, then verify with an actual request.

Before comparing results, note whether you’re on Wi-Fi or cellular, make sure no large transfer is underway, and keep the test target and method consistent. If you want to compare servers, don’t change networks or Global Routing at the same time. Repeatable results depend on stable conditions, not on getting one unusually good number.

Use a Few Repeat Tests to Check Consistency

Test the currently selected record first to make sure the test completes, then test other records in the same group as needed. If results fluctuate, check whether only one record changes or the whole group changes together. A slowdown across the group points more toward the local network or a shared route; persistent failure on one server points toward its settings or remote status. Don’t delete a record based on a single result.

After testing, try an actual request for your intended use and confirm that its traffic follows the expected route. If Global Routing is set to Direct, successful access doesn’t prove the server works. In Config mode, rules may send some requests directly. If the app shows request details, check the route used so you don’t mistake a successful direct connection for a verified proxy connection.

When an actual request fails, describe the stage—for example, DNS resolution failed, the connection timed out, TLS returned an error, or the remote server responded. Each points to a different check: look at DNS and routing for resolution issues, credentials for authentication failures, and Config for rule issues. Repeatedly tapping the test button only repeats the same observation; it doesn’t explain the failure.

Sort to Help Choose, Not to Replace Judgment

If the current interface offers sorting by latency, use it after a complete round of tests so you don’t mix old and new results. Results without measurements, failed tests, and valid measurements may be sorted differently; check each status after sorting. The first item is only at the top under the current sort order, not a permanent best choice. Network changes may make earlier results irrelevant.

For everyday use, keep a few verified records as candidates and organize or collapse the rest by source. This preserves alternatives while reducing the need to test the entire list each time. Choose candidates based on stable connections, clear source details, and real-world access—not latency alone. Testing helps you choose; it isn’t a rating of any service provider.

If you’ve confirmed that a server and routing mode work together, keep them as a baseline while checking other records one at a time. Don’t bulk update, delete, or rename records before preserving that baseline; without it, you can’t tell whether a problem came from a recent change or the network. For routing modes, see the Global Routing guide. For common connection issues, see Troubleshooting.

Confirm What You’re Deleting

Deleting one server, deleting a subscription entry, and removing a Config are different actions. If you delete a server generated by a subscription, a later update may recreate it. Deleting a subscription entry may also affect its entire group. Read the confirmation prompt to understand whether you’re removing one record or a whole group; don’t infer the scope from a long-press gesture or the list’s appearance.

If you only want to stop using a server for now, select another verified record instead of deleting it. Before removing a record, make sure it isn’t your only working connection or referenced by the active Config. For a local copy with an unclear source, check whether you saved the original settings. Without recovery details, deleting it leaves you with nothing to compare and forces you to collect the information again.

Removing a record from the list doesn’t revoke exposed credentials or change your remote account. If you’re cleaning up because you suspect a subscription URL or password was exposed, get replacement details from your service provider and follow their process for handling old credentials. Local deletion only changes the record on this device; it doesn’t update credentials remotely.

Back Up Three Layers

First, save subscription entries and source notes. Second, save settings for separately added servers. Third, save Config files and any rules you need to keep. A subscription URL can retrieve a remote list, but may not restore manually added records or rules. Exporting Config doesn’t guarantee that it includes every subscription credential or app setting. Check what each export actually contains.

If the app offers iCloud sync or export, check the available options and completion status before deciding whether they cover your device transfer. Turning on sync doesn’t mean everything has reached the other device, and it doesn’t guarantee you can undo an accidental deletion. Sync keeps device states aligned; a backup preserves a recoverable copy. Before important changes, keep a separate copy of your data.

Backups, QR codes, and sharing links may contain authentication details. Store them somewhere only the necessary people can access, not in public documents or albums. Label materials with their purpose and contents; don’t put passwords in filenames. After saving, open the file and confirm that it’s complete so you don’t discover during a device transfer that it’s empty or just a web page.

Restore in Order: Purchase, Import, Select, Verify

On a new iPhone or iPad, first check your purchase and restore the app through the App Store. Check the App Store listing for purchase eligibility and system requirements. Your app purchase gives you access to the app; it doesn’t guarantee that servers, subscriptions, or Config will be restored automatically. For purchase steps, see the guide to restoring a previous purchase. Rebuying the app isn’t a solution to missing data.

1. Confirm the app is from the correct App Store listing, then open it for the first time.
2. Restore synced data or import a backup, then check that subscriptions, individual records, and Config are all present.
3. Update subscriptions as needed, then confirm the selected server and Global Routing.
4. Run Connectivity Test and verify real-world access before removing data from the old device.

If records with the same name appear after restoration, identify whether each came from sync, export, or a new import before removing duplicates in bulk. Keep a verified set as a baseline, then remove extra copies. If the new device behaves differently from the old one, compare the network, Config, server settings, and system permissions one by one. Matching list names don’t guarantee identical settings.

For a detailed migration workflow, see Config backups, iCloud sync, and device migration. In routine maintenance, update and delete as separate steps: verify the new data first, then remove old items. This preserves a clear rollback path and gives you a complete, understandable starting point for future troubleshooting.