Clash Troubleshooting Guide

No internet access: separate your local network from the proxy path

Pinpoint where the connection fails

Turn off the system proxy and TUN mode, then try a site that normally works without a proxy. If it still fails, check whether the Wi-Fi requires a sign-in, the Ethernet cable is connected, and the operating system has a valid gateway. The issue is outside Clash’s scope at this point. Public Wi-Fi sign-in pages usually need a direct connection; reconnect the client and test again after signing in.

If direct access works but fails with the proxy enabled, check the core status instead of relying on the tray icon. Open the client’s logs and confirm that the configuration loaded and the listening port started. Look for repeated errors such as failed configuration parsing, an address already in use, or the core exiting immediately after launch. The client UI and mihomo core are separate processes: an open window doesn’t mean the local proxy service is running.

Find the mixed port in your settings. The example below uses local port 7890; replace it with the port you actually use before testing. This command explicitly specifies the proxy, removing the question of whether your browser reads the system settings. On Windows, use curl.exe to avoid PowerShell environments where curl may resolve to a different command.

curl.exe -I --connect-timeout 10 --max-time 20 --proxy http://127.0.0.1:7890 https://example.com/

If the command can’t connect to the local address, check the listening port, core status, and any blocks recorded by local security software. If it connects to the local proxy but then times out, check the policy group and remote connection. Receiving HTTP response headers—even with an error status—means the request reached the server response stage; don’t classify it as a proxy that failed to start.

Use logs to check rules and policy groups

Switch to Rule mode, open the proxy page, and make sure the policy group matched by the request has a usable exit selected. Some configurations route traffic through multiple groups, so changing the default group won’t affect other routes. Visit the target once, then find its domain in the connections page or logs. Check the rule type, policy group, and final policy; don’t use a successful request to another site as evidence for this one.

rules:
  - DOMAIN-SUFFIX,example.com,Proxy
  - GEOIP,CN,DIRECT
  - MATCH,Proxy

This example assumes your configuration already has a proxy or policy group named Proxy; it is not a complete configuration to import on its own. Rules are evaluated from top to bottom, and evaluation stops at the first match. If an earlier rule sends the target to reject or direct, the final MATCH rule won’t override it. Change only the rule for the target and preserve the original order so you can roll back.

You can briefly switch to Global mode as a comparison, but make sure an exit is selected in the global policy group too. If Global works and Rule mode doesn’t, narrow the issue down to rules, a policy group, or related DNS behavior. If both fail, check the local listener and exit they share. Switch back to Rule mode after testing; don’t leave a temporary diagnostic setting in place as a permanent fix.

Resolve conflicts, then verify recovery

While troubleshooting, let only one tool handle network traffic. Other VPNs, browser proxy extensions, older proxy clients, and packet-capture tools may also change the connection path. Quit them one at a time and retest; don’t uninstall network adapters or reset the entire network stack. If direct access still fails after the client exits, check for a system proxy setting that still points to a local port. A proxy setting left behind after the service stops can make the whole device appear offline.

After recovery, test one direct connection and one proxied connection, then check that each matched the expected policy. A page loading is only the outcome; the connection entry point and rule route in the logs are what help pinpoint the issue. If only the browser fails but command-line tests work, see the system proxy section. If errors are limited to name resolution, continue with the DNS section instead of repeating every step.

Node timeouts: distinguish port, handshake, and destination failures

Start with the stage where the error occurs

A timeout means a wait exceeded its limit; it doesn’t identify a single cause. The client may be unable to reach the node server, the protocol handshake may be stuck, or the exit may be unable to reach the destination. Save the full error context, especially the server address, connection method, and whether the failure occurred during dialing, TLS, or response reading. The last few words alone leave out the most useful clues.

First, check the scope: does one node fail for every destination, or only for one site? Do other nodes in the same subscription work? Does switching to a phone hotspot help? Change only one condition in each comparison. If all nodes fail only on one Wi-Fi network, look first at network restrictions, sign-in status, or exit policies—not at every node’s protocol settings.

Make sure the client is using the current subscription, not an old configuration with a node of the same name. Select the target configuration, then go back to the policy group and confirm the selection. Some groups use automatic selection or failover, so the final exit may change after testing starts. Use the policy shown in the logs, not just a node’s one-off check result.

Check the server address and TCP reachability

On Windows, use Test-NetConnection to check a server’s TCP port. The reserved example address below shows the command format only; use the server and port from your configuration for a real test. This checks neither proxy credentials and protocol settings nor UDP availability—it only tells you whether a TCP connection succeeded.

Test-NetConnection -ComputerName 192.0.2.10 -Port 443

If TCP is unreachable, check whether the server is under maintenance, the subscription is up to date, the local firewall is blocking the process, or the network restricts that port. A successful connection still doesn’t guarantee the proxy will work: incorrect credentials, transport settings, TLS server names, or protocol options can all break the handshake. For subscription-managed nodes, try updating the subscription first instead of guessing at authentication fields.

If the logs show certificate verification errors, first sync the system date, time zone, and clock, then check the node domain and certificate settings. Don’t treat disabling certificate verification as a general fix; it can hide server misconfiguration or connection interference. Browser certificate warnings may also involve the system trust chain. See Why HTTPS Certificate Errors Occur for a focused checklist.

A server specified by domain name also depends on DNS during startup. If that domain can’t be resolved, the remote connection hasn’t even started; changing the destination website won’t test this layer. Check which name appears in the error: the node domain or the site you’re visiting. The former calls for a reachable bootstrap DNS path; the latter calls for checking DNS and routing rules. They aren’t the same setting.

Separate test results from real-world traffic

A node check usually sends a small request to a specific test URL. It can give misleading results if that URL is blocked, responds differently, or doesn’t suit the network. Conversely, a successful check doesn’t guarantee that video, games, or every site will work. Test a regular HTTPS request first, then the actual destination, and see whether the issue is limited to a particular service. Don’t delete every node based on one test.

Games and calls may also rely on UDP. If web pages load but real-time apps fail, check whether the node protocol and server support the required transport and whether the client’s traffic capture includes the app. A TCP port check can’t stand in for a UDP test, and a browser speed test says nothing about UDP connectivity. If you don’t know what the server supports, ask your subscription provider instead of repeatedly toggling settings.

Repeated reconnects create noisy logs that can hide the first error. Pause automatic checks, select one exit, and capture a complete connection attempt. Then compare it with another known-good exit. If the second exit works, save the failing stage and test time for the service provider. If all exits behave the same way, look at the common layer: local networking, DNS, or the client’s traffic entry point.

Recovery means a real request completes reliably, not just that the test button reports success. After testing, restore automatic selection and check that you’re no longer in temporary Global mode. If the same issue recurs, note the network, node type, and failure stage. Those details help distinguish a change in network conditions from a stale subscription or an exit that’s consistently unavailable.

Subscription failures: check the download path and configuration parsing

Separate download failures from import failures

Subscription updates have two stages: fetching the content and parsing the configuration. Timeouts, refused connections, and HTTP errors happen during the fetch stage. If content arrives but the client reports a YAML error, invalid field type, or missing policy reference, the problem is in parsing. Check the update error on the configuration page, then find the corresponding log entry. Repeatedly clicking Update won’t change the request path or fix invalid syntax.

Check that the subscription URL is complete and that copying it didn’t drop trailing parameters or add spaces or line breaks. Subscription URLs often contain account credentials. Never post one on a public forum, online converter, or screenshot. If you need help, share only the domain, status code, and error type, with private identifiers removed from the path. If the link has been exposed, regenerate it with the provider; deleting the message isn’t enough.

Being able to open a provider’s homepage doesn’t mean its subscription endpoint is reachable too. The homepage and subscription may use different domains, access controls, or delivery paths; one may return a web page while the other requires valid credentials. For responses such as unauthorized, forbidden, or too many requests, check your account and update frequency against the provider’s instructions. Don’t try to bypass limits with repeated requests.

Check the network path used for subscription updates

If a subscription domain is reachable only through a proxy, but the current configuration has no working node, you can end up in a loop: you need a proxy to update, but need the update to get a proxy. Switch to another known-good configuration or use a network that can reach the endpoint directly, then update. Clients differ in whether subscription downloads use a proxy; check the relevant configuration setting instead of assuming the system proxy applies to requests made by the core.

After updating, check that the nodes and policy groups appeared, then confirm the client is using the configuration you just updated. Some clients keep multiple configurations and don’t switch automatically after a successful download. If the logs still show an old server, check the selected configuration, refresh status for remote proxy providers, and whether overrides retained an old address. Don’t mistake a selection issue for a cache problem.

If the response is a login page, access verification page, or plain error message, saving it with a YAML extension won’t make it a valid configuration. The parser may point to a character in the returned web page, not a mistake in the original subscription rules. Use a trusted local text editor to inspect the file’s opening lines and structure. Don’t upload a full configuration containing account details to a public syntax checker.

Track down YAML and reference errors

YAML indentation uses spaces, with keys at the same level aligned. Common mistakes include a missing space after a colon, full-width punctuation introduced during copying, and lists written as plain strings. The reported line is where the parser found a conflict; the actual cause may be on the line above. Check nearby lines and their nesting before deleting an entire policy group just to clear the error.

proxy-groups:
  - name: Proxy
    type: select
    proxies:
      - DIRECT

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

This structural example includes only DIRECT in the policy group to demonstrate name references; it doesn’t provide a remote proxy. The rule’s Proxy must exactly match the group name. Remote proxy providers and rule providers also need matching definitions. A typo, change in capitalization, or override that renames an item can prevent a successfully downloaded configuration from loading.

If the client offers a configuration check, run it before enabling the configuration. Command-line users can run the command below from the configuration’s directory. If the configuration uses relative paths, use the correct working directory. A successful check means the core can read the file; it doesn’t prove that every remote node is reachable or that the rules fit your needs.

mihomo -t -f config.yaml

If the subscription works until you enable it, temporarily disable local overrides, merge scripts, or extra configuration, then compare with the original subscription. If the original works, the issue is likely in the modification layer. Restore changes one at a time to find the cause; don’t overwrite your only backup. When syncing across devices, also check whether each client supports the same override format. See How to Sync Configurations Across Devices.

Keep provider-supplied remote content separate from your local custom rules. If an update fails, retain the last working configuration and switch only after confirming the new one loads. If the subscription keeps returning server errors, send the provider a redacted status code, timestamp, and client name. Reinstalling the operating system or clearing all app data won’t fix a server-side problem.

Slow speeds: pinpoint DNS, connection, and transfer delays

Define what “slow” means first

A long wait before a page opens, slow loading after it starts, and inconsistent large downloads point to different stages. Note whether the delay is before the transfer or during it, and test the same destination repeatedly. Slow on the first try but fast on the second may involve DNS, connection setup, or app caching. If the whole transfer stays slow, check Wi-Fi signal, the exit route, and server-side rate limits.

For speed tests, keep the device, network, destination, and policy group selection fixed. Pause system updates, cloud sync, and other bandwidth-heavy tasks. Check Wi-Fi signal quality first; use wired Ethernet for comparison if possible. A phone hotspot can help isolate a home broadband issue, but it also changes the carrier route. It narrows down the cause; it doesn’t prove that a node or client is faulty.

Check the final policy in the logs and confirm the slow request uses the intended exit. If a rule sends a site to a different policy group, changing the default group won’t affect its speed. Pages with resources on several domains may use different routes for the main document and static assets. If the page appears but images stall, check the rules or remote connection for the affected resource domain.

Compare timings by stage, not just by a test result

The command below reports cumulative request timings for before-and-after comparisons in the same environment. Use curl.exe on Windows and curl on macOS or Linux. Replace the proxy port with your actual setting. When HTTPS is accessed through an HTTP proxy, the proxy may resolve the domain, so local DNS time isn’t the full DNS time for the destination.

curl.exe --proxy http://127.0.0.1:7890 --connect-timeout 10 --max-time 30 -o NUL -sS -w "connect=%{time_connect} tls=%{time_appconnect} first=%{time_starttransfer} total=%{time_total}\n" https://example.com/

These timings accumulate from the start of the request; they aren’t independent durations. A quick connection followed by a long wait for the first byte may point to the proxy handshake, remote connection, or server processing. A longer total time may simply mean more content. On macOS and Linux, replace the output file NUL with /dev/null. Don’t compare total times across different sites as a measure of route quality; their responses and server behavior differ.

A node check measures whether a small request completes in time; it doesn’t measure download bandwidth. Routes may also handle single and multiple connections differently, so browser downloads, video streaming, and speed-test tools may produce different results. Repeat tests with the same resource you’re authorized to access, then compare another exit. Don’t keep changing core timeout settings just to improve a test result.

Rule out protocol, routing, and traffic-capture differences

If speeds drop only in TUN mode, first make sure no other VPN is running, then check the logs for duplicate route capture or connection loops. A brief system-proxy comparison can help separate the app entry point from the exit route. If the system proxy works but TUN doesn’t, don’t immediately replace every node. Check the virtual adapter, DNS capture, and network adapter selection, especially on devices with virtual machine or container networks.

Some apps prefer UDP-based transport. If the current exit can’t handle that traffic, the app may stall while waiting before falling back to TCP. In a controlled test, temporarily disable the app’s related transport option and see whether it recovers. Note the change and restore it afterward. Don’t block UDP globally: calls, games, and other services may depend on it.

An MTU mismatch can leave small requests working while larger transfers stall, but it isn’t the default explanation for every slowdown. Investigate it only if the issue reliably occurs on a particular network or TUN path while other entry points work. Make small changes based on your client and network documentation, and keep the original value. Randomly lowering the MTU increases packet counts and can hide the actual route or server issue.

If performance degrades only after long sessions, check for repeated reconnects on the connections page, continuous debug-log writes, or a device that’s in power-saving mode or overheating and throttling. Close the app generating abnormal requests, then see whether client resource use drops. High log verbosity is useful for short investigations, not as a permanent setting. Disk writes and UI rendering can also affect low-spec devices.

When you’re done, retest the same destination on the same network and entry point. Compare whether the original delay is gone. If only one site remains slow while other services work, note its domain, matched policy, and time window, then investigate the destination or exit route. Don’t treat one congested site as a client-wide performance issue or infer a guaranteed speed from a single test.

DNS issues: check resolution paths and Fake-IP mappings

First find out what handles the DNS request

A domain resolution error in the logs can originate from the operating system, browser, mihomo, or node server. A successful system lookup doesn’t prove the core’s upstream works. A browser using its own secure DNS may also bypass system resolution. Check the traffic capture mode and DNS settings, then test with the right tool; a result at one layer doesn’t prove another layer is working.

Start with the domain named in the error. If the node server’s domain can’t be resolved, the proxy connection can’t start. If the destination site’s domain can’t be resolved, the connection may already be underway. With encrypted DNS, the resolver’s hostname may also need to be resolved first. Distinguish these names to identify whether the issue is bootstrap, proxy-server, or regular destination resolution—and avoid a dependency loop.

On Windows, use Resolve-DnsName example.com to check the system path; on macOS and Linux, use nslookup example.com. Before testing a specific DNS server, confirm its address and listening port. System tools usually use the standard DNS port, so they can’t directly test every local listener. A successful command only means that one query got a response; check the client logs to see what happened to the actual request.

Know what to expect from Fake-IP

Fake-IP mode may return a mapped address from a reserved range. This is one way the core associates a domain with a connection, and doesn’t by itself mean DNS has been poisoned. What matters is whether connections to that mapped address still pass through the same core. If the client handles DNS but the connection bypasses it, the app may try to reach an address that exists only in the mapping table and fail.

dns:
  enable: true
  listen: 127.0.0.1:1053
  enhanced-mode: fake-ip
  fake-ip-range: 198.18.0.1/16
  nameserver:
    - 223.5.5.5
    - 119.29.29.29

This is a partial DNS configuration example to merge into an existing configuration; don’t declare the top-level dns key twice. The two upstream addresses are examples and should be replaced with resolvers reachable on your network. The local listener uses a non-standard port on the loopback address and won’t change system DNS automatically. Whether system queries are captured also depends on client settings, TUN, and the platform. Don’t assume every app will switch after importing this.

Printers, casting devices, and apps that need real addresses on your LAN may require specific names to be excluded with fake-ip-filter. First confirm how those names resolve and which local DNS server they use, then add only what’s needed. Excluding every domain changes the behavior of the entire mode and makes comparisons difficult. For the details and limits, see Fake-IP Mode Explained.

Check caching and encrypted DNS dependencies

After changing DNS modes, the operating system and browser may still cache old addresses, and apps may reuse existing connections. Follow this order: save the configuration, reload the core, close the target app, clear only the necessary cache, then test again. On Windows, run the command below to clear the system DNS cache. It won’t clear the browser’s own cache or fix an incorrect answer from the server.

ipconfig /flushdns

Don’t clear all client settings and caches at once. If the issue is a mismatch between Fake-IP mappings and an old connection, restarting the affected app and rebuilding the mapping is more targeted than deleting the entire data directory. If it started after waking from sleep, check whether the network changed, the virtual interface recovered, and old connections are still bound to the previous network before restarting the core.

With DoH or DoT, check that the upstream address is reachable, its certificate is valid, and rules aren’t sending the upstream through a proxy that hasn’t been established yet. Encryption doesn’t make a resolver automatically reliable; queries still fail if the connection can’t be established on the current network. Compare first with a known-reachable plain DNS resolver to identify the problem layer, then restore your encrypted setup rather than changing resolvers at random.

If problems occur only on IPv6-only networks or dual-stack connections, check whether the logs show an IPv4 or IPv6 address and compare it with the routes actually available on the device. Having an IPv6 address doesn’t mean every exit supports IPv6 connectivity. You can adjust IPv6 settings in a controlled test, but don’t treat disabling IPv6 as a standard fix for every DNS issue.

After fixing the issue, retry a previously failing domain and a LAN destination to make sure public routing and local discovery both work. If needed, record the system DNS, core upstream, and browser-specific DNS settings to keep their roles clear. If only one domain returns an unexpected result, check authoritative DNS and routing rules first; there’s no need to reset DNS across the whole device.

System proxy not working: check the app entry point and port type

The system proxy doesn’t cover every connection

The system proxy provides an address to apps that choose to read that setting; it doesn’t force all network traffic through a proxy. Browsers, command-line tools, store apps, and games use different network libraries and may behave differently. If web pages work but one app still connects directly, check whether it supports the system proxy or has its own proxy setting. Consider TUN only after that—don’t change a subscription that already works.

Make sure the proxy address points to the device’s loopback address and that the port matches the client settings. HTTP, SOCKS, and mixed ports aren’t interchangeable. Sending an HTTP proxy request to a SOCKS-only port may result in a closed connection or protocol error. If the client has a mixed port, it can accept supported proxy protocols on the same listener, but the app still needs the correct proxy type.

First test with a command that explicitly specifies the proxy, then compare it with an app request that doesn’t. If the explicit request works but the browser doesn’t, check browser extensions, its own proxy settings, whether it reads the system proxy, and the bypass list. If both fail, check the local listener or node connection. This separates “the app never reached the client” from “the client couldn’t forward the request.”

Check the actual settings on each platform

On Windows, netsh winhttp show proxy shows the WinHTTP proxy status, but it isn’t a complete mirror of the browser’s user proxy settings. Don’t assume the client’s system proxy is off just because WinHTTP reports a direct connection, and don’t import an entire settings profile to fix one app. Identify the app’s network stack first, then follow its documentation—especially for programs running as a service.

After switching between Wi-Fi, Ethernet, or another network service on macOS, make sure the client updates the currently active service. If you use an automatic proxy configuration script, check for conflicts with manual HTTP, HTTPS, or SOCKS settings. Managed work devices may have policies that overwrite saved values. Check with your device administrator instead of repeatedly forcing changes.

Linux command-line programs often read environment variables such as http_proxy, https_proxy, and no_proxy, but support varies by program. New variables usually affect only processes started from that terminal; they won’t change apps that are already running. To test temporarily, pass the proxy to a single command. That’s easier to undo than changing the entire session or system configuration.

curl --proxy socks5h://127.0.0.1:7890 --connect-timeout 10 --max-time 20 https://example.com/

socks5h means the proxy resolves the destination domain. This can help rule out local DNS issues, but only if the port accepts SOCKS requests. Letting the local device resolve the domain creates a different test path. Note the protocol and where resolution happens, and keep both consistent when comparing results. Using the same port alone doesn’t mean the tests are equivalent.

Check for bypass rules and sandbox restrictions

Check the system or app bypass list. If the target matches a direct-connection rule for local networks, specific domains, or an automatic configuration script, it won’t enter the proxy as expected. Adjust only the target’s rule; clearing the entire bypass list may disrupt local services and workplace resources. Browser extensions can also control proxy decisions, so temporarily disable them and use the system settings as the only entry point while troubleshooting.

Some Windows UWP apps are also affected by loopback restrictions: the proxy listener works, but the app can’t connect to the loopback address. See How to Fix UWP Loopback Restrictions and add an exemption for the target app, or use TUN where appropriate. Don’t grant access to every app, or apply this platform-specific issue to regular desktop programs.

Before using TUN, close conflicting VPNs and make sure the required client service or permissions are in place. TUN changes how traffic is captured; it can’t fix a dead node or invalid subscription. After testing, check whether the system proxy still needs to be enabled too, and note the final combination. For basic setup, see the System Proxy Quick Start. Use target connections appearing in the logs as evidence that it works.

Client crashes: separate the UI, core, and configuration data

Find out which process is exiting

A closing window, disappearing tray icon, and lost connection aren’t necessarily caused by the same process. Check Task Manager or Activity Monitor to see whether the UI is still running, whether the mihomo core keeps restarting, and whether an error appeared before the exit. If the UI is unresponsive but the proxy still works, investigate rendering and app data. If the UI works but the proxy stops, check core logs and configuration loading first.

Note what triggers the crash: on launch, after switching configurations, when enabling TUN, or after waking from sleep. A short set of steps that reliably reproduces the issue is more useful than a long account of random use. Copy the logs from before and after the exit to a separate file before restarting. Repeated launches may overwrite logs, and clearing app data removes useful diagnostic evidence.

Also check operating system event logs, available disk space, and security software block history. A full disk, unwritable directory, or quarantined core file can all prevent startup. Don’t disable all security protection. First identify the blocked file and its download source, then follow the security software and client documentation. Ask your administrator to check policy restrictions on managed work devices.

Check the installer and runtime environment

The installer must match your operating system and CPU architecture. Don’t mix Windows or macOS builds, or Linux package formats, based on similar-looking filenames. Choose the right platform from the client downloads page; Clash Plus is a good starting point for most users. Linux users should also check distribution dependencies, the desktop session, and the exact package-manager error instead of replacing system libraries.

If problems start after an upgrade, exit all old processes first. An old UI may be connecting to a new core, or multiple instances may be competing for the same port. Portable folders, system installation directories, and startup entries may each contain a copy. Check the actual path used by the running process before deciding what to remove. Don’t delete similarly named folders without checking; they may contain the active configuration and backups.

If the logs report that an address is already in use, identify the process using it before changing ports. On Windows, run the command below and replace the port with the actual listening port. Check the process ID in Task Manager. Don’t force-close an unknown process just because it’s using the port; it may be another working instance or local service.

netstat -ano | findstr :7890

If the port belongs to another proxy client, exit that client normally before starting the current one. When changing a port, update the system proxy, app-specific proxy settings, and related scripts too. Otherwise, the core may start again while apps keep sending requests to the old address. The control API port and traffic proxy port serve different purposes; don’t swap them just because their numbers look similar, and don’t expose the control API to an untrusted network.

Use minimal changes to pinpoint configuration issues

If only one configuration causes a crash, first disable local overrides and scripts, then check the original content. Large custom rule sets, duplicate remote providers, or scripts that repeatedly error can increase startup time and memory use. Restore extensions one at a time to identify the cause. Switching to another large configuration isn’t a useful comparison and doesn’t prove the core itself is faulty.

To test with a clean app state, first export subscription details, override rules, and policy selections, then back up the original data directory to a separate location. Temporarily move the original directory as described in the client documentation, then launch the test. Don’t recursively delete directories if you’re unsure what they contain. If the fresh state works, the issue is related to the original data; restore items gradually to identify the specific file instead of permanently discarding your settings.

If the issue occurs only with TUN enabled, check service permissions, the virtual interface, and other VPN drivers instead of reinstalling the whole app. If the UI freezes only when opening the logs page, try lowering the log volume and stopping repeated requests. These symptoms involve different components. Describe the full sequence so maintainers can tell whether UI or core logs are needed.

A final test should cover a cold start, configuration load, one request, and a clean exit; check recovery from sleep too if relevant. Record the client name, system architecture, trigger steps, and redacted error. Don’t guess the version; find it on the About page. If you still need to switch clients, keep the original data and see Clash Client Comparison for differences in UI, traffic capture, and configuration compatibility.

Mobile troubleshooting: VPN permissions, background limits, and network changes

Check the system VPN status first

Mobile clients usually rely on the system VPN interface to capture app traffic. On first launch, approve the system permission. A VPN status icon only means the interface is active; it doesn’t prove the remote node is reachable. Open the client logs and send a request from the target app to confirm that it reaches the core and matches the expected policy. If no connection appears, check traffic capture scope and app exclusions first.

Enable only one VPN-style service while troubleshooting. A work VPN, a filtering tool built on the local VPN interface, or another proxy app may compete for the system interface; starting one can disable another. On managed devices, check whether the app is in the personal or work profile. Apps in one profile may not use the network path established in the other.

On Android, start with Clash Plus, or choose Clash Meta for Android, FlClash, or Surfboard based on your needs; supported configuration features and menus vary. For iOS, see the iOS download page for Clash Plus. The official site is clashplus.io. Don’t apply desktop-only service modes or system proxy steps directly to a phone.

Android background activity and per-app proxying

If the connection works with the screen on but drops when locked, check battery optimization, background activity restrictions, and the manufacturer’s autostart settings. Allow the client to run in the background if needed, then see whether it still gets stopped. Power-saving options may be spread across app info, battery management, and background launch settings, with different names on different devices. Don’t remove restrictions for every app to fix one client.

With Always-on VPN or blocking connections outside the VPN enabled, the system may continue to block network access if the client stops. That’s an expected protection behavior. Note the original setting and temporarily disable it for comparison; restore it after troubleshooting if needed. If you only exit the app without checking the system state, this can look like a Wi-Fi problem.

When proxying only selected apps, check whether the client is using an allowlist or a blocklist. Choosing the wrong list type can leave the target app connecting directly. Whether newly installed apps are added automatically also depends on the client. After changing the app list, fully close and reopen the target app so it doesn’t keep using an existing connection. Verify browsers and in-app web views separately; they may run in different processes.

An app may also use its own DNS, a specialized protocol, or a fixed IP address. One working browser doesn’t prove that every app is being captured. Find the target request in the logs, then check whether the issue is the entry point, a rule, or an unsupported exit. For Android setup and import basics, see the Android Quick Start. Don’t repeatedly re-import the same configuration while troubleshooting.

iOS and recovery after network changes

On iOS, make sure the system VPN configuration belongs to the client you’re using. Turn off other VPNs that may connect automatically, then start the current connection. If the status in Settings doesn’t match the client, stop the connection normally, restart the app, and check the app name when authorizing again. Don’t delete a managed work configuration without checking with your organization about its network requirements.

After switching from Wi-Fi to cellular, existing connections may still be bound to the old path. Wait for the network switch to complete, reconnect in the client, then close and reopen the target app. If only cellular fails, check cellular data permissions for the client and target app, carrier restrictions, and the node’s transport. A network switch also changes DNS, address family, and routing; don’t assume the node is at fault.

For hotel and airport Wi-Fi that requires a web sign-in, stop the proxy to complete authentication, then reconnect. If the system requires all traffic to use a VPN, the sign-in page may not appear; temporarily adjust that restriction and note the change. After signing in, confirm direct access works on a regular page, then test the proxy. Don’t keep changing subscriptions or DNS before authentication is complete; it makes the problem harder to isolate.

A phone getting online doesn’t mean a tethered device can use the same network path. The operating system may not route shared traffic through its VPN, and some clients don’t support this. Don’t assume that a successful connection on the phone means tethered devices are proxied too. For an explicit LAN proxy, confirm client support, listening scope, and access controls, and enable it only on a trusted network.

After troubleshooting, test with the screen on, after locking and unlocking, and after switching between Wi-Fi and cellular. Check that the target app still matches the expected rule. If only one scenario fails, note the scenario and system restrictions instead of reinstalling each time. Compare common controls and log fields with the Client Interface Overview. Before returning to normal use, restore any temporarily disabled security settings and keep a working configuration backup.