Clash Troubleshooting Guide

Connection, subscription, DNS, system proxy and client issues. Find guidance by symptom and narrow down the cause with evidence.

For installation, importing a profile and your first connection, follow the Getting Started guide. This manual helps diagnose and recover from connection problems. If setup is not yet complete, start with the guide. If a previously working setup has stopped, choose the closest symptom below. Both paths follow the same rule: change one thing at a time and test before proceeding.

Ports in this guide are examples, not client defaults. Menu names may vary across clients such as Clash Plus and Clash Verge Rev; use your actual settings and core logs as the source of truth. Export your configuration before switching clients. If you need a different installer, see Clash Plus and clients for each platform in the download center.

No Internet Access: Trace the Request from Local Entry to Remote Exit

First, determine the scope of the problem

A working client interface and an enabled proxy switch do not prove that network requests are succeeding. Note when the issue started, the network type, the current configuration and the affected apps. Then test one site that should normally work without a proxy and the site that is failing. Repeat with the proxy disabled: if both fail, check Wi-Fi, the gateway or network sign-in first. If only the proxied test fails, focus on the local listener, rules and remote exit.

Temporarily quit other proxy clients, browser proxy extensions and tools that may control network settings. This prevents two apps from repeatedly overwriting each other's settings. Don't delete your configuration or enable system proxy and TUN at the same time as a guess. Keep the current logs and reproduce the issue with one traffic-capture method at a time. On managed devices, follow your organization's policies; don't remove security software to troubleshoot a conflict.

Test with an explicit proxy to bypass system settings

Check the mixed port in the client settings and confirm the core is running. The port below is an example; replace it with the actual listening port. Specifying the proxy explicitly lets you rule out whether the browser honors system proxy settings. On Windows, use curl.exe to avoid aliases that may mask the command; on other platforms, use curl.

curl --noproxy "" --proxy http://127.0.0.1:7897 \
  --connect-timeout 10 --max-time 25 \
  -I https://example.com/

If the local connection is refused immediately, the request never reached the proxy core. Check the core status and port first. If the request times out while waiting for the remote host, inspect the destination, matched rule and exit in the logs. An HTTP response, even an unsuccessful one, means part of the connection succeeded. Server-side rejection, sign-in requirements and content restrictions are not the same as a local proxy failure. These commands check response headers only; if a site doesn't support that request method, retry with a regular GET request.

Check rule matching separately from exit availability

Open the connections or logs view, reproduce one failed request and check which rule matched the domain, which proxy group was used and which exit that group selected. In rule mode, traffic may go direct or match a reject rule. Switch briefly to global mode for comparison only. If global mode works but rule mode doesn't, inspect rule order and proxy group selection. If both fail, investigate the exit connection instead of repeatedly changing the routing rules.

A webpage may depend on separate login, static asset and API domains. If the homepage loads but the sign-in button keeps waiting, inspect the failing subrequests instead of adding a rule for the homepage alone. Use the browser developer tools' Network panel to identify failed domains, then compare them with the client connection logs. Before sharing screenshots, redact query parameters, account identifiers and subscription details from full URLs. The error name and matched rule are usually enough.

Verify recovery against the same destination: confirm that the explicit proxy request works, then test the browser and other apps that need a proxy. Restore rule mode and turn off temporary debug logging; don't leave test settings in place as your everyday configuration. If the browser still fails but the command works, see the system proxy section. If the logs show a resolution error, see the DNS section. For a shorter step-by-step checklist, see Connected but Can't Open Websites? A Troubleshooting Checklist.

Node Timeouts: Check DNS, Handshake and Data Transfer Separately

Pinpoint where the timeout occurs

A timeout in the interface may come from a connectivity-check URL or a real application request; the two are not interchangeable. One failed check does not necessarily mean the exit is unusable: the test destination may restrict access, or the test request may be affected by routing rules. Select one exit, retry the same destination a few times, then inspect the logs for that time. Distinguish DNS lookup failures for the server hostname, connection timeouts, protocol handshake failures and slow responses from the destination site.

A refused connection usually means the destination rejected it or an intermediary actively blocked it. A connection timeout only means the expected response didn't arrive in time; it doesn't prove the server is offline. Authentication errors and certificate name mismatches are different clues, not problems to hide by increasing the timeout. The full error message is more useful than a screenshot showing only a red timeout label.

Check the system clock and server endpoint

Enable automatic time synchronization and confirm that the date and time zone are correct. Certificate-based connections check certificate validity periods, so an incorrect system clock can cause repeated handshake failures even with a working configuration. Next, confirm that the server address, port and transport settings still match the subscription. Missing a path, service name or transport setting when copying a node can allow the underlying connection to start while the proxy protocol handshake never completes.

To test a server port separately, run this command in PowerShell. The example hostname is for illustration; replace it with the server address in your configuration. A successful result only confirms that the TCP port is reachable; it doesn't verify authentication, TLS or the proxy protocol. A failed test says nothing about services that use UDP only. Don't share your full node configuration just to test a port.

Test-NetConnection -ComputerName example.com -Port 443

Don't disable certificate verification as a routine fix. For certificate errors, check the server name, system trust chain, system clock and whether a managed network inspection device is in use. If the configuration requires a specific SNI or transport path, confirm the parameters with your service provider rather than guessing. Updating a stale subscription may replace an outdated endpoint, but back up local overrides first.

Use a network comparison to identify local restrictions

Keep the same device, configuration and destination, and switch only from the current Wi-Fi network to a phone hotspot. If the hotspot works and the original network doesn't, the issue is likely on the original network path, its sign-in state or its access policy. Then compare with another device on the same network. Don't change the client and exit at the same time; too many variables make it hard to identify the cause, even after service returns.

Some networks allow only specific connection types, and UDP may be restricted in particular. If TCP websites work but apps that rely on UDP fail, check that the exit protocol, core and remote service support the required traffic. TUN can capture app packets, but it can't make an exit that lacks UDP support handle UDP. For IPv6 issues, compare the address family actually used; an unreachable route doesn't mean every entry point is broken.

Log clueCheck firstDoes not prove
Failed to resolve server hostnameBootstrap resolver, upstream DNSThe remote service is offline
Connection to server timed outNetwork path, address family, portThe subscription is corrupted
Authentication or handshake failedCredentials, clock, transport settingsIncreasing the timeout will fix it

If only one endpoint fails while others work under the same conditions, give your service provider the failure time, error type and network comparison results. If all endpoints fail while direct access works, check the client core, DNS and local firewall. Stop running frequent repeat checks and restore a reasonable interval. Repeated concurrent probes clutter logs and may trigger remote limits, making the problem harder to diagnose.

Subscription Failures: Check the Link, Response and Configuration Merge

Distinguish download failures from parse errors

A subscription update involves several stages: requesting the URL, retrieving the content, parsing the configuration and applying it. Download timeouts usually occur in the first two stages. A parse error may mean the content arrived but isn't a supported configuration. Identify whether the error concerns the network request, HTTP status, YAML syntax or core validation; don't assume every failure means the link has expired. Export the working configuration before updating so you don't overwrite your last usable copy.

Copy the subscription link again from your provider's account page. Check that the clipboard didn't add line breaks, spaces or punctuation from a chat app. Subscription links often contain access credentials; never paste them into public converters, online YAML validators or public support tickets. A link opening in your browser only proves the browser made a request. It doesn't prove the client used the same proxy, headers or network path—or that the response is a compatible configuration.

Check the actual response content

If the client shows download details, check the status code and response type first. A webpage, login screen or access verification page may be interpreted as YAML, producing an error that looks like a syntax problem. A successful status doesn't guarantee valid content; the server may return explanatory text with a success code. Inspect the beginning of the file locally to see whether it contains a configuration, node text or webpage content. Don't upload the full file if it contains credentials.

Subscription formats vary between clients. Content generated for another protocol or app does not become a Clash configuration just by changing its file extension. Select a format compatible with Clash or mihomo in your provider's settings, then import it again. If the configuration references proxy providers or rule providers, check that those external resources can also be downloaded after importing the main configuration. Importing the main file doesn't mean its dependencies are ready.

Find YAML and override configuration errors

If parsing fails after a local edit, check that indentation uses spaces, keys at the same level align and list items retain their hyphens. Quote strings containing special characters where needed, but don't blindly quote every number or Boolean. The snippet below is a valid partial structure for checking syntax, not a complete, ready-to-connect configuration. The subscription supplies the actual proxy groups and exits.

mixed-port: 7897
mode: rule
log-level: info
allow-lan: false

rules:
  - DOMAIN-SUFFIX,example.com,DIRECT
  - MATCH,DIRECT

A client may merge the original subscription with global overrides, scripts and interface options before passing the result to the core. The source file can be valid while the final configuration fails because it references a missing proxy group. Temporarily disable recently added overrides or scripts, then apply the original subscription. If it works, re-enable items one at a time to find the conflict. Don't rely on editing an auto-updated source file; the next update may overwrite your changes.

For automatic update failures, check whether the app can run in the background, whether the device sleeps and which units the update interval uses. Clients may store intervals in minutes, hours or seconds; don't copy a value from another app without checking. Avoid repeatedly requesting a broken link at very short intervals. Update successfully by hand first, then restore the schedule. For the exact settings and troubleshooting steps, see Subscription Auto-Update Interval Guide.

To confirm recovery, check more than the last updated time: make sure the intended configuration is selected, the core applied it successfully and all referenced proxy groups exist. If the server keeps returning invalid content, send the provider a redacted status code, error line number and request time. For more on format errors, see How to Troubleshoot Subscription Parse Errors. For subscription basics, visit the Help Center.

Slow Speeds: Separate Connection Delays from Slow Data Transfer

First, identify when the slowdown occurs

A page that stays blank for a long time and then appears all at once is a different problem from a download that starts quickly and then slows down. The first may involve DNS lookup, connection retries, a handshake or a blocked critical resource. The second may point to exit capacity, packet loss, remote throttling or poor local Wi-Fi. First determine whether all sites, one site or one type of app is slow. Compare the same destination, file and network to avoid mistaking differences between servers for client performance issues.

The browser developer tools' Network timeline can distinguish time spent connecting, waiting for the first byte and downloading content. A stalled analytics script or font may also delay the page's completed status. Client logs add details about exits and rules, but can't show all the page's dependencies. Find the slow request, then check whether it uses a direct or proxied route. That's often more useful than repeatedly switching the entire configuration.

Compare results with the same entry point and destination

Pause OS updates, cloud sync and other bandwidth-heavy tasks, then test with a single download. If Wi-Fi is unstable, move closer to the access point or compare once over a wired connection. Don't run multiple speed tests at once or rank exits based on a single probe. A test URL's response time describes only that test path—not large-file throughput or the experience on the site you actually use.

To inspect an explicit proxy request, use curl to report timings for each stage. The command below keeps the regular page output and prints timings at the end; replace the destination with the same fixed test URL each time. When accessing HTTPS through an HTTP proxy, some timing fields include proxy negotiation, so don't treat any one field as the remote server's standalone response time. Compare repeat tests under the same conditions instead of drawing conclusions from one number.

curl --noproxy "" --proxy http://127.0.0.1:7897 \
  --connect-timeout 10 --max-time 30 \
  --write-out '\nconnect=%{time_connect} tls=%{time_appconnect} first=%{time_starttransfer} total=%{time_total}\n' \
  https://example.com/

If direct requests are also slow, check the local network and destination site first. If only one exit is slow, compare it with other working exits in the same configuration. If one site is slow through every exit while other sites work, the cause may be server load, regional routing or app-level restrictions. Reinstalling the client is unlikely to help. Record the destination, time and selected exit so you can repeat the test later; don't just note that it's slow.

Check for inefficient routing and transport differences

A rule that sends a resource that could go direct through a remote server may add connection latency. A rule that sends a proxy-required API request direct may cause lengthy retries. Check whether the homepage and API domains are routed through different exits, especially for sign-in services that require session consistency. Change only clearly incorrect domain rules; don't add large, unknown address ranges to a global bypass list. Reconnect after making changes because existing connections may keep using their original exit.

A browser may try HTTP/3 over UDP first, then fall back to another connection method. If the network or exit doesn't support that path, the fallback delay can make the first load intermittently slow. Check the client, exit protocol and network support before running a controlled browser comparison. Disabling a protocol can help identify the cause, but shouldn't be presented as a universal optimization for every device.

With TUN, consider path MTU or network equipment behavior only if small pages work but larger requests stall. Don't copy an MTU value from the internet or change DNS, the protocol stack and MTU all at once. Keep the original value and compare against system proxy mode. If the issue occurs only with TUN, use the logs and network details to adjust one setting at a time. Proxying can't eliminate packet loss on the underlying network, and a virtual adapter won't increase link capacity.

Verify recovery with real tasks: open the same webpage, sign in to the same service and download the same resource. Remove temporary test conditions and restore your usual rules; keep only settings that demonstrably help and whose effect you understand. If the issue occurs only at certain times, recording when it happens is more useful than repeatedly changing the client. If only one app is affected, check its cache, extensions and separate proxy settings.

DNS Issues: Understand Resolution Across the System, Apps and Core

First, find out which component resolves the domain

DNS issues can make a domain unreachable, delay the first page load or produce different results across apps. System DNS, browser Secure DNS, app-specific resolvers and mihomo DNS may all be active. Note the failing domain, error and traffic-capture method. Reaching an IP address directly is only a clue, not a substitute for testing the HTTPS domain: certificates, hostnames and virtual hosting may all depend on it.

A successful lookup with a system tool doesn't prove the client uses the same DNS path. An explicit HTTP proxy can usually resolve the target domain remotely; whether a SOCKS request resolves locally depends on how the client makes it. A browser using its own Secure DNS may also bypass the system resolver. Test one path at a time and record which tool you used instead of comparing results from different resolvers as if they were equivalent.

Know what the main DNS parameters do

nameserver specifies regular upstream resolvers. default-nameserver can resolve the hostnames of upstream DNS servers, providing a bootstrap lookup when an upstream is specified by hostname. proxy-server-nameserver resolves proxy server hostnames; this is separate from resolving the domains you visit. fallback and its filters help select candidate results. They are not simply a list of backup resolvers called in order after every request times out.

The snippet below shows the minimum structure for observing fake-ip mode; it doesn't include a full TUN or routing configuration. Upstream addresses are examples—choose resolvers that are reachable on your network. The listener is restricted to localhost to avoid exposing DNS to the LAN unnecessarily. If the client already manages DNS through its UI or an override file, make changes through that same interface so multiple sources don't overwrite each other.

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  default-nameserver:
    - 1.1.1.1
  nameserver:
    - https://dns.cloudflare.com/dns-query
  fake-ip-filter:
    - "*.lan"
    - "*.local"

In fake-ip mode, the core returns a virtual address that it maps internally; it isn't the website's real server address. Seeing an address in a test range doesn't by itself mean DNS is broken. The key question is whether subsequent traffic still reaches the core that maintains the mapping. If an app bypasses TUN after receiving a virtual address, or keeps a stale address after the core restarts, DNS may appear to work while the connection fails.

Recover in the right order: cache and traffic capture

Apply the configuration and confirm the core has started. Then clear relevant system and app caches and retry the request. On Windows, use the command below to clear the system DNS cache. Browser caches and connection pools may require a browser restart. Use the appropriate method on other operating systems; don't treat a Windows command as universal. Repeatedly clearing caches can change the symptoms, but won't fix an incorrect upstream or traffic-capture path.

ipconfig /flushdns

TUN DNS hijacking typically applies to specified DNS traffic; it doesn't mean all app-level encrypted DNS is captured. A DNS listener on a nonstandard port won't make the system send queries there automatically; that requires matching system settings or TUN forwarding rules. If the logs show no DNS requests, first verify that requests are reaching the core before changing upstreams. Otherwise, you may be changing settings that aren't being used.

Treat LAN device names, corporate intranet domains and multicast names separately. Public resolvers usually can't resolve internal names, so forcing every query to a public upstream may break printers or internal services. Configure resolution rules or fake-ip filters for the domains and network you actually use, while preserving the existing internal DNS path. Filtering a domain only changes how it's handled; it doesn't guarantee the system can resolve it.

To verify recovery, test a regular website, the domain that failed and any internal services you need. Also confirm that proxy server hostnames resolve reliably. If disabling a DNS setting fixes the issue, record which path that setting affects before deciding whether to keep it disabled. For more on DNS parameters and hijacking, see mihomo DNS Configuration Explained. Don't replace the entire DNS section just to remove one error from the logs.

System Proxy Not Working: Check the Port, App and Traffic Capture Method

Verify the local listener before checking the system proxy

The system proxy switch writes proxy settings to the OS; it doesn't guarantee that every program will use them. First confirm the core's port with an explicit proxy request. Then check that the system proxy host is a loopback address and the port matches the client. After changing the mixed port, system settings, browser extensions and terminal environment variables may still point to the old value. Check each entry point instead of relying only on the new number shown in the client settings.

With a port conflict, the core may fail to start or another process may occupy the expected port. In Windows PowerShell, you can identify the listening process; on macOS or Linux, use lsof. Replace the example port with the actual one. Identify the application before stopping a process—don't terminate an unknown system process. Close the conflicting app or choose an unused port, then apply the settings again.

# Windows PowerShell
Get-NetTCPConnection -LocalPort 7897 -State Listen |
  Select-Object LocalAddress, LocalPort, OwningProcess

# macOS / Linux
lsof -nP -iTCP:7897 -sTCP:LISTEN

Check browsers, terminals and system services separately

Browser proxy extensions can override system settings, and some apps have their own proxy controls. Terminal tools often read HTTP_PROXY, HTTPS_PROXY, ALL_PROXY and NO_PROXY, but support varies by tool. Environment variables are usually inherited when a process starts, so an open terminal or editor may not pick up changes immediately. A working browser doesn't prove that background services use the same proxy.

On Windows, the user's proxy settings differ from the WinHTTP settings used by some system services. When troubleshooting a service, check its environment with netsh winhttp show proxy. Don't treat importing or resetting WinHTTP as a standard fix for regular browser issues. On macOS, check the active network service, not a disconnected interface. On Linux, desktop proxy settings depend on the desktop environment and the app.

MethodHow traffic is capturedWhat to check
System proxyApps follow the system proxy settingsSystem address, port and app overrides
Explicit proxyThe app specifies a proxy entry pointProtocol, listener address and bypass list
TUN modeRoutes and a virtual network interfacePermissions, routes, DNS and other VPNs

Check permissions and routes separately for TUN mode

For apps that ignore the system proxy, consider TUN. Before enabling it, make sure the client's service component is installed and the required permissions are granted. An enabled TUN switch doesn't prove that the virtual adapter and routes were created successfully. Check the logs for device creation failures, missing permissions or route conflicts. Test supported network stack options one at a time; don't change the stack, DNS and exit together.

Other VPNs, virtual machines, containers and security software may use overlapping TUN routes. Quit nonessential network tools and compare system proxy with TUN. The core must be able to connect to its own remote server; incorrect routing may send that connection back through the proxy and create a loop. If the client uses automatic routing or interface detection, confirm that it selected the currently active network interface.

To share the proxy on a LAN, enable LAN access and set the listener address and firewall scope correctly. On another device, 127.0.0.1 points to that device itself, not the computer running the proxy. Don't disable the entire firewall or expose the local proxy port to the public internet. Allow access only from trusted LAN devices, and review the access rules if the network changes.

If internet access doesn't return after quitting the client, check whether the system proxy still points to a local port that is no longer listening. Disable the stale setting manually, then check whether another app has configured a proxy or automatic configuration script. Once the connection is restored, start one client and verify it; avoid multiple startup entries overwriting one another. For the difference between system proxy and TUN, see the Help Center. For the recommended first-time setup, follow the Getting Started guide.

Client Crashes: Isolate the UI, Core and Configuration

First, identify which part stopped

A closed window, a client still running in the tray, a stopped core and a fully exited process are different issues. Check the tray icon and system process list, then see whether the logs are still updating. If closing the window sends the app to the tray, that's usually a setting, not a crash. If the interface still works but the core keeps restarting, check configuration application errors, resource paths and permissions before blaming the UI.

Note the last action before the crash: importing a subscription, updating the app, switching TUN, waking from sleep or signing in. Match the end of the app log with system error records from the same time. You don't need to send the entire configuration directory. Logs may contain server addresses, visited domains and file paths; redact them first. For a repeatable issue, clear reproduction steps are more useful than a large set of screenshots.

Back up first, then try a minimal startup

Quit the client and confirm its processes have exited, then copy the configuration directory to a separate location. The backup should include subscriptions, override files and necessary user settings, but don't upload it to a public cloud drive. Next, start a test environment using a separate configuration directory or reset method supported by the client. If you don't know where the data directory is, check the setting that opens it. Don't delete unknown files from your user directory as a fix attempt.

If the minimal environment starts, import a known-good configuration and restore overrides, scripts and interface settings one at a time. If the problem returns after restoring an item, you've narrowed down the cause. Fix configuration errors using the reported line and final merged result. For UI database or window state issues, there's no need to change proxy protocols. If the installer includes its own core, don't replace it manually with a file of unknown origin or compatibility.

To validate mihomo configuration syntax locally, use the core's test option. The command below assumes the executable and test configuration are in the current directory. It checks whether the core accepts the configuration; it doesn't guarantee that servers are reachable, rules behave as intended or subscription resources remain available. Command output may also include sensitive file paths, so review it before sharing.

# macOS / Linux
./mihomo -t -f ./config.yaml

# Windows PowerShell
.\mihomo.exe -t -f .\config.yaml

Check architecture, runtime and permissions

Before downloading again, confirm the operating system and processor architecture, especially Intel versus Apple Silicon and the package architecture for Android devices. A successful installation doesn't guarantee that all dependencies are available. Graphics runtimes, system components and installation directory permissions can also prevent startup. Address the specific missing component or system error reported by the app; don't install batches of repair tools from unknown sources.

On Windows, use Event Viewer to identify the faulting module. On macOS, check crash reports and app launch logs. On Linux, check user session logs and output from launching the app in a terminal. Terminal output can reveal missing graphics dependencies, but don't run the entire desktop app as an administrator to hide the problem. If a service component needs elevated permissions, use the client-provided installation and management process.

If security software quarantined a component, check the quarantine record, installation source and reason before taking action; don't disable protection by default. An unwritable install directory or a file locked by sync software can also leave an update incomplete. Quit the app completely, then use the download center to choose an installer for your operating system and reinstall. Keep a data backup so uninstalling doesn't remove configurations or logs you still need to inspect.

Clash for Windows and ClashX Meta are no longer maintained. If they have compatibility issues with a newer operating system, consider moving to a client that supports your current environment. Clash Plus is the first choice; on Linux, also consider Clash Verge Rev or FlClash. Import your configuration and verify basic connectivity before restoring custom features one at a time. Don't copy an entire settings directory between clients: compatible configuration syntax doesn't mean their internal data formats are the same.

Mobile Troubleshooting: VPN Permissions, Background Activity and Network Changes

On Android, check VPN access and app coverage

Android clients typically route traffic through the system VPN interface. The first connection requires system permission. If permission is denied or restricted by device policy, the app may look normal without capturing any traffic. Check the system VPN status and client logs, then look for another VPN, a work profile or an app using the same scope. A VPN icon in the notification bar doesn't prove that the exit or DNS is working.

Clash Plus, Clash Meta for Android, FlClash and Surfboard use different configuration formats and settings menus. Select the right format when importing; don't assume every Android client accepts the same configuration. If per-app proxying is enabled, confirm that the affected app is in the intended scope. Some interfaces use an include list and others an exclude list. Misreading the setting can leave a specific app going direct while the browser works.

Always-on VPN and blocking connections that don't use the VPN are separate system controls. If the block option is enabled, losing the tunnel may block network access as intended; it doesn't necessarily mean Wi-Fi is broken. Note the original settings before comparing behavior. On organization-managed devices, follow the device policy and don't change work profile security settings.

Troubleshoot background interruptions separately from installation failures

If the connection fails after the screen locks but returns as soon as you reopen the app, check battery optimization, background activity limits and the manufacturer's auto-start controls. Allow the necessary background activity, then test a full lock-and-wake cycle. Disabling every battery-saving setting doesn't identify the cause and can reduce battery life. If the background process is still running but the connection fails when switching from Wi-Fi to mobile data, investigate network reconnection and DNS rather than granting more background permissions.

If installation reports an incompatibility, check the OS requirements and processor architecture. An update over an existing app may also fail because of a signature or installation source mismatch. Export your configuration before uninstalling; app data may be deleted with it. Don't downgrade or install an unknown package to bypass an error. Compare clients and architectures in the Android downloads section; follow the guide for the initial import.

On iOS, check tunnel configuration and resource limits

On iOS, visit the iOS downloads section for the Clash Plus App Store page. The client website is clashplus.io. For connection issues, check that the VPN configuration in iOS belongs to the current client and confirm that the app has permission to create a tunnel. Stale configurations, other network tools or device management policies may affect the connection; use the specific status shown by iOS to guide troubleshooting.

On iOS, the network extension runs separately from the foreground interface, so an open app doesn't prove the tunnel is still working. Large configurations, too many rule resources or frequent updates may add load to the extension. Retest with a smaller, known-good configuration and restore external resources gradually. Don't assume a background restriction means the subscription is corrupted, and don't keep reinstalling the app without logs to support that diagnosis.

SymptomCheck firstHow to compare
Disconnects after screen lockBackground restrictions, tunnel logsTest locking the screen without changing networks
Only one app failsPer-app routing, rules and protocolCheck that app's request logs
Fails after switching networksTunnel reconnection, DNS and address familyTest Wi-Fi and mobile data separately

Test Wi-Fi, mobile data and captive portal sign-in separately

Public Wi-Fi may require browser sign-in before it allows internet access. If the proxy is enabled first, the sign-in page may not appear. Complete the network's sign-in process before enabling the client. Wi-Fi and mobile data may use different IPv6, DNS and routing paths, so create a new test request after switching networks. A configuration working at home doesn't rule out restrictions on an office network or hotspot.

A phone hotspot doesn't necessarily share the phone's VPN traffic capture with connected devices; behavior depends on the OS. When a computer connects to a phone hotspot, verify the computer's system proxy or TUN settings separately. After restoring mobile access, test screen lock and wake, network switching and the affected app. If the problem persists, note the OS, client, network conditions and redacted logs, then continue with the relevant section of this guide.