Before You Install: Check the App and Your Configuration

1. Where should I install a Clash app for iPhone?

Start with the client downloads page to find the iOS option, then follow the selected app’s instructions to its store listing. Before installing, check the app name, developer, and supported iOS versions. App Store results can vary by account region. If a name doesn’t appear, don’t assume a similarly named search result is the same app.

Desktop .exe and .dmg installers can’t be installed on an iPhone. iOS clients may also have different names from their desktop counterparts. Choose one that supports your configuration format rather than relying on “Clash” in the app name. If you already have a subscription, ask its provider which iOS clients it supports before installing an app.

2. Why can’t I connect right after installing the app?

The client reads your configuration, selects an outbound, and handles the relevant network requests on your device. Installing the app doesn’t provide a working remote node. You’ll typically also need a compatible configuration with reachable nodes. A subscription is one way to get or update a configuration; the subscription URL isn’t a latency test, and it doesn’t guarantee that every node will work.

First, identify what the configuration provider gave you: a subscription URL, an importable configuration file, or a link for a single node. Each may have a different import flow. If you only have a username and password but no configuration instructions, don’t guess at proxy port settings. Importing into an iPhone client is different from manually setting an HTTP proxy in Wi-Fi settings.

Import and Enable Your Configuration

3. Where do I paste a subscription link?

In the client, open “Configuration” or “Profiles,” tap “Add,” and look for an option such as “Import from URL” or “Subscription.” Paste the full URL and save it. Button labels vary by app, but the URL belongs in the configuration import screen—not the browser’s address bar or a node name field. When the import finishes, return to the configuration list and select the new entry to make it active.

  1. Copy the full URL from your provider, including the https:// prefix and any parameters at the end.
  2. On the client’s configuration page, choose URL import. If there’s a name field, enter a label you’ll recognize.
  3. Wait for the download and parsing to finish. Confirm the configuration appears in the list, then set it as the active configuration.
  4. Open the nodes or policy groups page and confirm that the available outbounds from your provider are listed.

If you received a local YAML file, use “Import from File” or the client’s supported file-sharing flow. Don’t paste the entire YAML file as a subscription URL. For your first import, follow the quick-start guide and check each step.

4. Getting “Download failed” or “Configuration parse failed”? Start here

First, work out which stage failed. A download failure means the client couldn’t retrieve the content. Switch between Wi-Fi and cellular, check whether the URL has expired or was copied incompletely, and confirm whether your subscription service requires sign-in or renewal. If you test the link in a browser, note that it may download a file directly. A page opening successfully doesn’t mean it returned a configuration the client can use.

A parse failure means the content was retrieved but couldn’t be read in the expected format. Common causes include a login page being returned, an incompatible subscription format, or indentation errors after editing YAML. YAML entries at the same level should use consistent spaces; don’t use tabs for indentation. If the configuration contains fields such as proxy-groups and rules, see the technical reference to learn what they do. If you’re unsure about the format, ask your provider for an import URL compatible with your client rather than repeatedly changing the file extension.

5. The connection switch won’t turn on. Which iPhone permission should I check?

The first time you connect, iOS usually asks for permission to add a VPN configuration. Make sure the prompt comes from the client you’re using, then approve it and complete the device passcode or Face ID check. Next, go to iPhone Settings → General → VPN & Device Management → VPN and check that the client’s configuration and connection status appear. Menu labels can vary slightly by iOS version; rely on the VPN status shown in Settings.

If the switch immediately turns off again, return to the client and confirm that a configuration and an available node are selected, then try connecting again. If another VPN or network extension is running, disconnect it first and retry. Don’t assume two apps that handle system traffic can work at the same time on iOS. A school- or work-managed device may also be restricted from adding VPN configurations; contact your device administrator if so.

After Connecting: Troubleshoot by Symptom

6. VPN says “Connected,” but webpages won’t load. What should I do?

“Connected” first means the system VPN configuration is active; it doesn’t confirm that a remote node is reachable. Try these three checks in order: open a site that normally works without a VPN, switch to another node in the client, then test once on Wi-Fi and once on cellular. Change only one thing at a time so you can tell whether the issue is your local network, the current node, or the configuration rules.

  • No websites load: Check the active configuration, selected node, DNS settings, and whether another VPN is conflicting.
  • Direct-access sites work, but a particular site fails: Try another node, then check which rule and policy group match the request.
  • It fails only on one Wi-Fi network: Test on cellular and check whether the Wi-Fi network requires you to sign in through a web page first.

If the client provides connection logs, check the entries around the time you accessed the site to see how the request was routed. For example, DIRECT means the request bypassed the proxy under the current configuration. If a policy group is shown, check which node that group selected. Don’t post a full URL containing your subscription key in a public forum.

7. Nodes are listed, but latency tests fail. Does that mean the subscription is broken?

Not necessarily. A node appearing in the list only means the configuration was loaded. A latency test also depends on its test target, your current network, and whether the remote connection is working. First confirm your phone has a working internet connection, then switch nodes and verify access by opening a webpage. If several nodes fail, update the configuration once and check for a service notice from your provider. If only one node fails, try another before deleting the entire configuration.

Latency isn’t download speed. An 80 ms test result means that particular request took about 80 milliseconds to respond; it doesn’t tell you whether video or large downloads will run smoothly. Compare nodes on the same Wi-Fi network and against the same test target. Results from Wi-Fi and cellular networks aren’t directly comparable.

8. Which mode should I use: Rule, Global, or Direct?

For everyday use, start with “Rule” mode. It checks requests against the current configuration’s rules in order and sends matching traffic to the corresponding policy group or outbound. Which sites go direct and which use a proxy depends on the configuration. “Global” usually sends all traffic handled by the client through the selected proxy outbound, making it useful for checking whether a failure is caused by rule matching. “Direct” sends handled traffic without a proxy outbound, which can help you check whether your basic network connection works.

When troubleshooting one site, you can briefly switch from “Rule” to “Global” and test it, then switch back. If the site works in Global mode but not Rule mode, check the matching rule and policy group instead of assuming the node is at fault.

The same mode name doesn’t mean different clients handle exactly the same system traffic. iOS clients typically use the system VPN interface to handle traffic. Desktop guide steps for a TUN toggle, system proxy port, or 7890 port setting don’t automatically apply to iPhone.

Keep Your Configuration Current: Updates and Quick Checks

9. Do I need to update a subscription after importing it?

Keep the update process in mind. When you import a subscription, the client downloads a snapshot of the configuration at that time. Later changes to nodes or rules may not appear on your phone automatically. In the client’s “Configuration” or “Profiles” page, find the current subscription and tap “Update.” When it finishes, check whether the node list has changed. Some clients offer automatic update intervals, but the setting and whether updates run in the background depend on the app. An interval doesn’t guarantee a successful update every time you open the app.

Before updating, note which configuration and node you’re using. If a policy group is renamed, you may need to select your preferred node again. If an update fails, keep the old configuration and check your network and subscription expiry. Editing a local file by hand usually won’t change the remote subscription. If you want to keep custom rules, first check how your client supports local configurations or overrides.

10. What should I check first to get connected again quickly?

Start with the easiest things to verify. Don’t reinstall the client, delete the configuration, and change DNS all at once. First disconnect and confirm that common websites load on your current Wi-Fi or cellular network. Then check the selected configuration, mode, and node in the client. Reconnect and verify the status on the system VPN page. If it still fails, try another node, then test on a different network. This should help narrow the cause to your network, node, or rules.

  1. Basic network: Disconnect the client and confirm that Wi-Fi or cellular data works on its own.
  2. Configuration and permissions: Check the active Profile, system VPN permission, and connection status.
  3. Outbound selection: Choose another node in the policy group and see whether webpages load.
  4. Rule comparison: Briefly switch between Rule and Global modes and compare the results for the same site.
  5. Subscription update: Check the update result and your provider’s status instead of repeatedly testing an outdated node list.

If you contact your configuration provider, include your iOS version, client name and version, whether you’re on Wi-Fi or cellular, the exact error message, and when the issue occurred. Before sharing screenshots, hide your subscription URL, account details, and personal browsing history. These details are more useful than “it won’t connect” and make it easier to reproduce the troubleshooting steps.