Clash Troubleshooting Guide

No internet access: separate the underlying network from the proxy path

Disable traffic capture and establish a direct connection baseline

Quit other proxies, accelerators, and VPNs, then turn off the current client’s system proxy and TUN. Try a site you can normally access directly, and open your router’s admin page. If both fail, check Wi-Fi, Ethernet, the gateway, and any network sign-in page. Public Wi-Fi often requires browser authentication; a proxy can prevent that page from loading. Restore automatic IP and DNS settings, complete sign-in, and then start the client.

Test direct access at two levels. Opening your router’s page confirms a path to the local network, but not that your internet provider’s connection is working. If other devices on the same network also can’t reach external sites, troubleshoot the router or upstream connection first. If only this device is affected, check its firewall, leftover proxy settings, and static routes. Don’t keep refreshing the subscription while the underlying network is down; that can make a network issue look like a broken link.

Test the entry point, rules, and exit separately

Once direct access is restored, start the client and confirm that the core is running and the configuration has loaded. An open interface doesn’t mean the proxy port is listening. Check startup logs for configuration errors, a port conflict, or insufficient permissions. Then enable only the system proxy; don’t turn on TUN at the same time. Check the mixed port shown in the client and explicitly specify that proxy in the command below. The port is just an example—change the command to match your configuration.

# macOS / Linux; on Windows, use curl.exe to run the equivalent command
curl --connect-timeout 10 --max-time 20 \
  --proxy http://127.0.0.1:7890 \
  --head https://example.com

# Bypass proxies set in environment variables for comparison
curl --noproxy '*' --connect-timeout 10 --max-time 20 \
  --head https://example.com

If the explicit proxy request succeeds but your browser fails, the core-to-site path worked for that request. Check the browser’s proxy settings, extensions, or system proxy handling. If the request can’t connect to the local port, check the listening address and port first. If it connects to the proxy but then times out, inspect the rule, policy group, and node used for that request. The test site doesn’t need to return a success status code; any valid HTTP response shows that the request reached a server.

If one site fails in rule mode, temporarily switch its policy group to a known-working node and compare the requested domain with the final policy in the connection log. Global mode can help identify a rule-related difference, but it doesn’t prove that all rules are wrong. Switch back to rule mode and find the specific match. If the connection hits REJECT, check the rule source and order; if it unexpectedly uses DIRECT, see whether an earlier rule matched the domain. Don’t delete the entire ruleset to hide one bad match.

Restore network access without leaving a half-configured setup

If TUN cuts off all internet access but system proxy mode works, check the virtual adapter, routes, and DNS handling before re-entering node credentials. Insufficient admin permissions, another VPN’s default route, or a subnet conflict can send traffic through the virtual interface without a working return path. Turn off TUN and confirm that routes are restored, then check the service mode as directed by the client. Don’t install multiple virtual adapter drivers in succession; troubleshooting is easier when one client handles network traffic.

If internet access still fails after quitting the client, check whether the system proxy points to an old local port and whether manual DNS settings remain. Note the original values before changing anything; don’t remove static settings required by a work network. After access is restored, open a new connection—an existing browser session may still use its previous connection. Pinpoint whether the fault is with direct access, the proxy entry point, rules, or the exit. That gives you a useful starting point for the next section, instead of just “nothing works.”

Node timeouts: identify what’s being tested and where it fails

Distinguish a failed latency test from a failed connection

A timeout usually means the request to a particular test address didn’t finish in time. It doesn’t mean the node is unusable in every situation. Select the node and try an accessible HTTPS site in your browser or with an explicit proxy command, then compare the result with the latency test. If browsing works, check the test address, timeout setting, and whether the site limits automated requests. Don’t delete an entire subscription based on one test address.

If all nodes time out, check whether the issue occurs on the same network, client, or during the same time period. A badly incorrect device clock can interfere with TLS certificate checks, so enable automatic time sync and confirm the time zone. Then check whether the node server’s domain resolves on your device. A website resolving correctly doesn’t guarantee that the server domain does; they may use different DNS paths. If the log reports a server name resolution failure, fix DNS before assessing node quality.

Check resolution, port access, and protocol in order

Once the server domain resolves, test TCP connectivity to its port. The examples below use documentation-only domains and ports. For troubleshooting, substitute the server address and port from your subscription, and run the test only on your own device. A successful TCP test shows that a connection reached the port; it doesn’t verify authentication, encryption settings, or UDP traffic. For protocols that rely mainly on UDP, a failed TCP probe alone doesn’t prove the node is down.

# Windows PowerShell: test TCP only
Test-NetConnection -ComputerName example.com -Port 443

# macOS / Linux: use if nc is installed
nc -vz -w 5 example.com 443

A connection refused error usually means the destination port isn’t accepting connections, or an intermediate device actively rejected the request. A timeout after waiting is more likely to indicate dropped traffic, an unreachable server, or blocked return traffic. These call for different checks. For a refusal, verify the server port and whether the remote service is listening. For a timeout, compare using another local network. Corporate, campus, and public Wi-Fi may restrict certain ports or protocols, so don’t assume the configuration is broken based on a test there.

If the transport connection works but the handshake fails, check the node type, password or ID, transport, TLS setting, server name, and path one by one. Some protocols also require a public key, fingerprint, or other transport parameters; missing fields may be ignored or trigger a parsing error. Reimport a compatible configuration from your provider first. Don’t piece together fields meant for a different core just because the names look familiar. Don’t leave certificate validation disabled to bypass a handshake error; first confirm that the domain matches the certificate.

Narrow down the cause with controlled comparisons

If one node fails while others work, start by checking that node’s settings and remote status. If all nodes fail on one device but work on another, compare core compatibility, security software, and local traffic handling. When testing another network, keep the node and configuration unchanged; when testing another node, keep the network unchanged. Changing the network, client, and subscription all at once may fix the issue without revealing why—and leave you likely to hit it again.

Make sure your node selection actually takes effect. A policy group may contain another group, an automatic selection group may switch back to a different node, and existing connections may continue using their established sessions. Check the full policy chain in connection details. If needed, close only the target app’s existing connection and make a new request. Don’t routinely terminate all connections to test speeds; that interrupts downloads and calls, and concurrent reconnections can distort results.

When contacting your provider, include the time of the issue, network type, protocol, failure stage, and a redacted error. Don’t share the full subscription URL. For a more detailed troubleshooting sequence, see How to troubleshoot when all nodes show timeout. Once the issue is resolved, keep a snippet of a successful request and restore any temporary test address or logging level to avoid carrying troubleshooting settings forward.

Subscription errors: check fetching, parsing, and activation separately

Start by checking what the subscription URL returns

Subscription issues fall into at least three stages: whether the client can download the content, whether it can parse the content, and whether it can activate the resulting configuration. Read the exact error first. Connection timeouts and DNS failures are fetch issues; line, indentation, or field-type errors are parsing issues. If import succeeds but no nodes appear, check whether the new configuration is selected and whether policy groups reference those nodes. Don’t treat every problem as a reason to reinstall the client.

Copy the subscription URL again from your provider’s site and make sure it has no line breaks, leading or trailing spaces, or punctuation added by a chat app. Subscription URLs usually contain account credentials; don’t paste them into public converters, screenshots, or online debugging tools. If opening the link in a browser shows a sign-in page, CAPTCHA, or service notice, you may have received HTML rather than a configuration. A successful HTTP status doesn’t guarantee the content is in the right format.

For an unauthorized or forbidden response, check whether the subscription was reset, account permissions changed, or the request was rate-limited. If the resource can’t be found, verify that the URL is complete. For a server error, note the time and retry later. Leave a gap between retries instead of repeatedly clicking Update. If the URL won’t load directly but works through an existing proxy, specify the update route if your client supports it. If the current configuration is unusable, first obtain a working local configuration to restore access.

Tell a full configuration from a proxy provider

A full Clash configuration can include proxies, policy groups, rules, and DNS. A proxy provider file usually contains only a list of proxies, referenced by a provider in the main configuration. They serve different purposes. Importing a provider URL as a full configuration may result in an empty interface or missing policy groups; importing a full configuration into a proxy-list-only field may cause a format error. Confirm the link type with your provider, then use the client’s configuration import or provider option as appropriate.

# Example structure for a full configuration; an empty proxies list provides no remote proxy nodes
mixed-port: 7890
mode: rule
proxies: []
proxy-groups:
  - name: Manual selection
    type: select
    proxies:
      - DIRECT
rules:
  - MATCH,Manual selection

The example above shows the configuration structure and defaults to direct access; it doesn’t include a usable proxy server. Use nodes from your own service configuration. YAML indentation uses spaces, with fields at the same level aligned and list items nested under the correct parent. When an error points to a line, check the preceding line too for a missing colon or quote. Don’t replace ASCII colons with full-width punctuation or copy the code-fence markers from a web page into the file.

Request headers can also affect the response format. Some subscription services generate different configurations based on the User-Agent, so downloading in a browser doesn’t mean the client will receive the same content. Change request headers only when the service documentation requires it, and use a supported client identifier. Impersonating another app at random may cause the server to return incompatible fields. If you see an unsupported protocol or unknown field, check which core the client uses and whether the subscription targets it, rather than deleting every field mentioned in an error.

Confirm that the new configuration is active

After import, check the configuration list for its update time and selected status, then open the proxy groups to confirm that nodes are present. Providers may need to be updated separately; an updated main configuration doesn’t mean its dependent resources have refreshed. A group filter that keeps only certain names can also leave the node list empty. Check the filter, provider loading errors, and any name changes before concluding that the service returned no nodes.

Local overrides, scripts, and merged configurations can rewrite rules or nodes after import. Back up the configuration, temporarily disable these processors, and compare the original with the final running configuration. Don’t edit a client-generated runtime file directly; it may be overwritten the next time the configuration loads. For changes you need to keep, use the client’s supported override option and keep the scope as small as possible.

Once the subscription is working again, update it manually, activate it, and verify with a new connection. Check that rules, DNS, and policy groups behave as expected—not just the node count. For more on formats and request headers, see Subscription update errors and YAML self-check checklist. If your provider has reset the URL, remove the old one so other devices don’t keep retrying with expired credentials.

Slow speeds: pinpoint first-byte delay, throughput, and app-specific issues

First, identify which part is slow

A page that takes a long time to start loading, a slow download after it begins, and video that pauses intermittently are different symptoms. The first may involve DNS, connection setup, or the TLS handshake. Low sustained throughput can point to congestion, remote throttling, or local resource limits. Intermittent pauses call for checks on packet loss, Wi-Fi interference, and app buffering. Keep the target, node, and network constant, and note the initial wait and sustained transfer speed. Don’t compare results from unrelated sites.

A client latency test isn’t a bandwidth test. A node that responds quickly to the test site may still have a poor route to a video or file server. Speed-test sites may also select servers in different regions, making results hard to compare. Start with a real-world comparison: use the same file, device, and time period over direct and proxy connections, and note whether only the proxy path is slow. Don’t run large downloads and multi-node speed tests at the same time; the test traffic will compete for bandwidth.

Use connection stages and policy logs to diagnose

The command below reports cumulative timings for name resolution, connection, TLS, and the first byte. With an HTTP proxy, some values describe the connection to the proxy entry point, not the remote node’s standalone response time. It’s best for comparing before and after under the same conditions, not for calculating a route’s true latency. Confirm the request succeeded before checking timings; an error page or cache hit can also return unusually fast.

curl --proxy http://127.0.0.1:7890 \
  --connect-timeout 10 --max-time 30 \
  --output /dev/null --silent --show-error \
  --write-out 'DNS:%{time_namelookup} CONNECT:%{time_connect} TLS:%{time_appconnect} FIRST:%{time_starttransfer} TOTAL:%{time_total}\n' \
  https://example.com

On Windows, use curl.exe, set the output target to NUL, and run the command on one line. If time to first byte is high but transfer speed is normal once it starts, check DNS, the handshake, the destination server’s response, and the route from the node to the destination. If it starts quickly but sustained throughput drops, compare other nodes, file sources, and local Wi-Fi quality. Don’t infer long-download performance from a single short request; congestion and throttling may affect them differently.

Open the connections panel and confirm the request is using the expected node. A page’s main domain, image hosts, video hosts, and download domains may match different rules; this matters when “the page is fast, but video is slow.” An automatic policy group may switch exits between tests. Temporarily pin a node for comparison, then restore the original policy. Some services limit cross-region sessions, and frequent node changes may trigger extra verification and make access worse.

Check the device, protocol, and network boundaries

Start by checking CPU, memory, and disk usage. Heavy debug logging, too many connections, real-time scanning, and other downloads can all become local bottlenecks. Laptop power-saving modes and thermal throttling on mobile devices can also affect encryption. For the test, close unrelated resource-heavy tasks and return logging to its normal level, then repeat the same request. Don’t leave the firewall disabled for speed tests; add only rules supported by a specific block log.

If only calls, games, or certain video apps are affected, check UDP support and how traffic is captured. Browsers may use QUIC, which a system HTTP proxy may not cover. In a controlled test, switch the app to TCP and see whether it recovers before deciding whether to adjust TUN or related rules. Protocol switching is a diagnostic tool, not a one-size-fits-all optimization. Check MTU only when evidence points to issues such as large transfers stalling while small requests work; record the original interface value before testing a small change.

A strong local Wi-Fi signal doesn’t mean there’s little interference. Moving closer to the router, using Ethernet, or trying another network can help distinguish a Wi-Fi issue from a proxy bottleneck. If different devices and clients all perform poorly with the same node and resource, the remote server or an intermediate link is more likely at fault. Give your provider the resource type, time period, and comparison results instead of piling on local tweaks. After testing, undo temporary rate limits, pinned nodes, and protocol changes so the configuration remains easy to understand.

DNS issues: check the resolver path and Fake-IP mappings

First, find out which layer is resolving the domain

If a domain won’t open while some existing connections still work, DNS may be involved—but don’t assume that’s the cause. Note any resolution errors in the logs, then check the system DNS address, whether client DNS is enabled, and whether the app uses its own encrypted resolver. The OS, browser, proxy core, and router may each have their own cache and resolution path. Changing one layer while testing another can produce contradictory results, so identify which resolver handles each test.

A proxy request may have the proxy server resolve the destination domain, so a failed local lookup and successful proxy access can occur at the same time. Resolving the node server’s domain is a separate issue. If DNS is needed before connecting to the node, but the chosen resolver can only be reached through that node, you have a bootstrap dependency. First ensure the resolver’s domain has a working bootstrap path, then check regular destination domains. Don’t route all DNS requests through a proxy connection that hasn’t been established yet.

Test the core’s DNS listener on an explicit port

The example below shows mihomo DNS fields, listening only on the local device on a dedicated test port. The public resolvers are configuration examples, not a guarantee of access on your network or a recommendation for privacy or routing. Before adding this snippet to an existing configuration, check for an existing root-level dns field and whether the client overrides it. Enabling a listener alone won’t make the system use it; the client must capture DNS traffic or you must query it explicitly.

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://cloudflare-dns.com/dns-query

# macOS / Linux: install dig, then test the specified DNS listener
dig @127.0.0.1 -p 1053 example.com A
dig @127.0.0.1 -p 1053 example.com AAAA

In Fake-IP mode, a domain resolves to a mapped address from a reserved range. That’s expected and doesn’t mean the website’s server is actually at that address. The core uses the mapping to recover the domain, then applies rules and forwards the request. If an app gets the mapped address and connects directly, bypassing the core, it may fail. To check Fake-IP, don’t just judge whether the result looks like a public IP; confirm that the same core handles the subsequent connection and that the mapping still exists.

After changing the enhanced mode, restarting the core, or switching configurations, the system and apps may retain old mappings. Close the affected app, clear its relevant cache, and make a new request. On Windows, run ipconfig /flushdns to clear the system cache, but remember that browsers, apps, and routers may have separate caches. Use each platform’s supported method rather than applying a command from one OS to every device. Fix the resolution path before clearing caches, or you’ll just reproduce the same error.

Handle internal domains, IPv6, and route conflicts

Printer, corporate intranet, and home storage domains often rely on local DNS or a specific search domain. Sending every domain to a public resolver may break these services. Set a resolution policy for domains that need local DNS, and add them to the Fake-IP filter if they need real addresses. Only add confirmed problem domains; a broad wildcard can change how many normal requests are handled and make the issue harder to reproduce.

Check both IPv4 and IPv6. If a domain returns an AAAA record but the device has no working IPv6 path, an app may wait for a failed connection before falling back, making the first load slow. You can temporarily compare behavior with IPv6 disabled at one layer, but distinguish between the OS interface, core DNS, and the node’s exit. Fix the path or use an explicit policy instead of disabling IPv6 everywhere and losing the ability to pinpoint the cause. Corporate networks may also have routes that conflict with the Fake-IP range; check existing subnets before changing it.

Browser Secure DNS can run alongside system DNS handling. If only the browser is affected, compare its Secure DNS settings. If only internal domains fail, check split DNS and local routes. Recovery means new lookups return results, new connections follow the expected policy, and internal services still work. A DNS answer alone doesn’t prove that it’s correct or that the connection path is secure. For field definitions, see the DNS and network stack terms in Quick Reference.

System proxy not working: check whether the app reaches the proxy

System proxy, environment variables, and TUN each have different limits

A system proxy typically gives HTTP proxy access to apps that honor the OS settings; it doesn’t guarantee that all device traffic is captured. Command-line tools, games, services, and apps with their own network stack may ignore it. TUN captures traffic through a virtual interface and routes, but can be affected by permissions, exclusions, and other network software. Find out which entry point the target app uses before choosing a fix. The system proxy toggle alone doesn’t prove that all device traffic is proxied.

The clearest first test is an explicit proxy command. If it succeeds but the target app doesn’t appear in the client’s connection log at all, check the app’s proxy entry point before changing nodes. If the request appears but uses DIRECT, investigate rules or policies. If it uses the expected node and still fails, check the exit. Make a new request while watching the connection log; existing long-lived connections may not move when system settings change.

Check the listener, environment variables, and platform settings

A local proxy often listens on a loopback address. If the client and app run in the same OS environment, 127.0.0.1 works. In a container, virtual machine, or some subsystems, loopback points to that environment itself—not necessarily the host. Determine the host address and access permissions for your network mode instead of copying a local command. If LAN access is required, configure the listening address, firewall, and authentication; don’t expose the proxy port to the entire network just to test a container.

Command-line tools may read HTTP_PROXY, HTTPS_PROXY, or ALL_PROXY, or only their lowercase equivalents; check the tool’s documentation. A running process usually won’t pick up environment variable changes. Set a variable temporarily in the current terminal and test before adding it to a global startup file. Also check NO_PROXY; an overly broad bypass may send the target directly. The example below applies variables to one command only to avoid leaving them set.

# macOS / Linux: set environment variables for this request only
HTTP_PROXY=http://127.0.0.1:7890 \
HTTPS_PROXY=http://127.0.0.1:7890 \
curl --head --max-time 20 https://example.com

# Windows: inspect the current user and WinHTTP settings; they are separate proxy entry points
reg query "HKCU\Software\Microsoft\Windows\CurrentVersion\Internet Settings" /v ProxyEnable
netsh winhttp show proxy

The Windows user proxy and WinHTTP service proxy are separate settings, and the output of one inspection command can’t stand in for the other. Don’t import global settings just because a service isn’t using the proxy; first check which account it runs under and what it supports. macOS proxy settings are configured per network service, so switching between Wi-Fi and Ethernet may use different settings. Linux desktop proxy settings aren’t necessarily inherited by background services either. After changing networks, confirm how the target app actually connects.

Check UWP apps, extensions, and leftover settings after an unexpected exit

Some Windows sandboxed apps are restricted from accessing local loopback addresses. Consider a UWP loopback exemption only after confirming the core’s proxy entry point works, regular desktop apps connect, and a specific app can’t reach the loopback port. Prefer the client’s management option and grant access only to the relevant app. An exemption changes local network permissions; it won’t fix node authentication, subscriptions, or remote connections. Remove the app’s exemption when it’s no longer needed.

Browser proxy extensions, automatic configuration scripts, and manual system proxy settings can override one another. Temporarily disable extensions, leave only one proxy source enabled, and check whether the target domain is on the bypass list. After a client exits unexpectedly, the system may still point to a closed local port, blocking the browser. Restore the original system settings before restarting the client, then confirm that the toggle and address match. If settings remain after every exit, collect exit logs instead of leaving a broken proxy configured and working around it by repeatedly restarting.

Client crashes: distinguish interface, core, and service failures

First identify which process stopped working

A window that disappears, a blank interface, a stopped core, and a failed service startup require different fixes. If the window won’t open but the proxy still works, the issue may be limited to the UI. If the interface works but the proxy port isn’t listening, check core logs. If only TUN fails to start, investigate service permissions or the virtual interface. Check process status in Task Manager or Activity Monitor and note the last error. Don’t delete all configuration just because the window is broken; it may contain the best clues for reproducing the issue.

Note what was happening when the crash occurred: did the client exit on launch, after loading a particular configuration, after enabling TUN, or only after running for a while? Each points to a different set of checks. For a startup failure, check file permissions, architecture, and runtime dependencies. If a configuration triggers the crash, inspect parsing and custom processors. For a crash after extended use, watch memory, connection count, and log growth. System event logs or crash reports can supplement client logs; remove usernames, paths, and access data before sharing them.

Use configuration checks and a minimal setup to isolate the issue

If your environment can run mihomo independently, use the core’s configuration test to check whether the file parses. Point the command to the actual configuration file; if it references external rules or proxy providers, make sure those resource paths exist too. A passing test confirms only that the configuration check succeeded—not that every remote node works or that it matches the final configuration after GUI overrides. If the client can show its runtime configuration, inspect that first rather than only the original subscription file.

# macOS / Linux: run from the directory containing the core
./mihomo -t -f ./config.yaml

# Windows PowerShell: run from the directory containing the core
.\mihomo.exe -t -f .\config.yaml

If the configuration check reports a port conflict, find out what’s listening before deciding to stop a process or change the port. Don’t terminate every process with a similar name; a system service or other app may be using it. If you change mixed-port, update the system proxy, in-app proxy, and command-line environment variables too. The control interface port and proxy port serve different purposes; pointing a browser at the control interface won’t create a normal proxy connection.

Keep a way to roll back during minimal-configuration testing. Copy the entire configuration directory, then temporarily disable scripts, overrides, custom rules, and extra providers, restoring one item at a time. If the minimal setup works, add the original components back until the issue returns. Don’t clear app data without a backup; it may contain subscriptions, policy selections, and local rules. Use the client’s settings or logs to find the directory; paths vary by platform and installation method.

Check system requirements and keep the setup recoverable

Installers must match your CPU architecture and OS; on Linux, check the distribution’s package format too. If security software blocks startup, inspect the specific block log and file source instead of disabling protection altogether. A read-only directory, low disk space, or a sync tool locking the user configuration directory can prevent saving or startup. For comparison, try a separate directory writable by a standard user, but don’t run all apps as administrator permanently.

A blank interface may involve the system WebView or graphics driver, but only for clients that depend on those components—not every Clash client. Confirm that the system component works, then follow the relevant client documentation. If core logs continue while the window stops responding, note whether this coincides with frequent connection refreshes or log scrolling. Reducing UI refresh load can help as a comparison, but don’t disable all logging and keep guessing about the cause.

If you need to reinstall, choose the right platform and architecture on the downloads page, then test a copy of your backed-up configuration. Clash for Windows and ClashX Meta are archived clients that are no longer maintained. If you run into compatibility issues on a newer OS, consider Clash Plus or another compatible client on the downloads page; switching interfaces won’t automatically migrate every setting. For a standalone Linux core setup, see How to deploy mihomo with systemd.

When reporting an issue, include your platform, architecture, client, steps to reproduce, configuration test result, and a redacted error snippet. If it occurs only with a particular configuration, reduce it to a minimal sample and remove real server credentials, then confirm the issue still reproduces. Once the client is working again, check system proxy and TUN settings; leftover settings after a crash can cause a second network problem. Finally, restore the normal logging level to keep logs from consuming disk space.

Mobile troubleshooting: permissions, background activity, and network changes

Android: check VPN permission and app selection

Android clients usually capture traffic through the system VPN interface. Approve the system permission on first launch. Another VPN, a work-profile network tool, or a security app may be using the same interface. Close other traffic-capture tools, start the client, and compare the system VPN status with the client logs. The status icon shows only that the system interface exists; it doesn’t confirm that nodes, DNS, or rules work. Make a new request and check which policy it matches.

Clash Plus, Clash Meta for Android, FlClash, and Surfboard differ in interface and configuration support. Don’t assume that fields supported by one client are supported by another. If import fails with a protocol or rule error, confirm that the subscription is compatible with the selected client. Surfboard’s configuration format isn’t interchangeable with every Clash YAML file. New users can establish a basic connection with the Getting Started Guide, then add per-app routing and custom rules one at a time.

If per-app proxy is enabled, check whether the mode proxies only selected apps or excludes selected apps. The lists may look similar, but the behavior is opposite. If the target app doesn’t appear in the connection log, it may be excluded or still using a cached connection. After changing the selection, close the app’s existing session and reopen it. If the browser works but other apps don’t, check their DNS, certificate requirements, or in-app proxy settings instead of blaming background permissions by default.

iOS: confirm the active configuration and system tunnel

On iPhone, use the iOS download option to open Clash Plus on the App Store; its official website is clashplus.io. After installation, import a configuration and approve the system VPN permission. Then confirm that the newly imported configuration is active. A file appearing in the subscription list doesn’t mean the tunnel is using it. After updating a subscription, check policy groups and verify the exit with a new connection.

iOS may also have multiple VPN configurations or other network extensions. Keep only one traffic-capture source active while checking that the tunnel connects. If apps work in the foreground but fail after the screen locks, distinguish between OS scheduling, a network change, and a remote long-lived connection closing. Don’t rely only on the client’s status when you bring it back to the foreground. Note when the interruption occurred and whether a new request recovers automatically. A brief reconnect and a persistent outage are different problems; report them separately.

If only one app is affected, compare a regular website, another way to access the same service, and the app’s connection log. The app or service may apply region, account, fraud-prevention, or server-side policies; a working proxy connection doesn’t guarantee that every feature will work. Avoid cycling through multiple exits for one app error, as that may trigger more checks. For the full download and import workflow, see Importing a subscription configuration in an iPhone client.

Shared checks for background activity, battery saving, and Wi-Fi changes

If Android disconnects after the screen locks, check whether the OS restricts background activity, battery use, or background data. Grant the required permissions through your device’s app settings instead of disabling power management for the whole device. Some systems stop network processes when clearing tasks; confirm the connection is stable in the foreground, then test with the screen locked and check logs for a process restart. If the process remains active but the connection fails, investigate the network and node rather than attributing every outage to system cleanup.

Switching between Wi-Fi and cellular changes the IP address, default route, and DNS environment, so existing connections may not survive. Keep to one network during testing, confirm it’s stable, then switch and note whether only the transition fails or new connections still can’t be made afterward. If rebuilding the tunnel after a switch restores access, focus on how network changes are handled. If failures continue on a fixed network, revisit the node, DNS, and background restrictions sections. Don’t judge node stability while moving between hotspots.

Mobile hotspots also have limits. A phone using a VPN doesn’t guarantee that a computer connected to its hotspot uses the same route; whether shared traffic enters the tunnel depends on the OS and client. Test on the connected device itself instead of relying on the phone’s status bar. On metered networks, pause bulk subscription checks and large speed tests so troubleshooting doesn’t consume data unnecessarily.