Troubleshooting

Start with the error message. On iPhone and iPad, errors appear in a card at the bottom of the Home tab and in the subscription card on the Me tab. On the Mac, they appear under the relevant row (System proxy, TUN mode), as notices above the panel footer, and in Settings › System status.

MeowX will not connect

iPhone and iPad

1. Is there a configuration? If the Home card says Not configured or “Subscription required”, import a subscription and make it current. See Your first connection.
2. Did you allow the VPN? If the status is Not installed, tap the power button and allow the “Add VPN configurations” prompt.
3. Is another VPN running? Only one VPN can be active. Turn the other one off in its app or in Settings › VPN.
4. Read the error card on the Home tab. Configuration errors (invalid YAML, a group referring to a name that does not exist, a rule pointing nowhere) are reported there. Refresh the subscription; if the error persists, it is in the subscription itself, so contact your provider.
5. Try Direct mode. If MeowX connects and websites work in Direct mode, the tunnel is fine and the problem is the node or the rules (see below).

Mac

1. Open Settings › System status in the panel.
2. System proxy mode: the System proxy helper must say it is enabled. If it says it needs approval, click Allow and turn on MeowX under System Settings › General › Login Items & Extensions › Allow in the Background. If it says the helper was not found, move MeowX to the Applications folder and open it from there.
3. TUN mode: the Network extension (TUN) row must say it is activated. If it needs approval, click Allow and turn MeowX on in Login Items & Extensions › Network Extensions (on macOS 14: Privacy & Security). If activation is stuck, click Activate again.
4. Another proxy client running? Quit it, or turn off MeowX’s System proxy toggle so the two do not overwrite each other’s settings.
5. Just turned TUN mode off? macOS can take up to about 30 seconds to release the local proxy port. Wait for the “Waiting for the system to release port” message to disappear.

Connected, but sites do not load

Work from broad to narrow:

1. Switch to Direct mode. If sites now load, MeowX and your network are fine; the problem is the node or the rules. If they still do not load, check your own internet connection without MeowX.
2. Switch to Global mode and pick a node with a good latency on the Nodes tab. If sites load now, a rule was sending them somewhere that does not work (for example to REJECT, or to a group whose current node is down).
3. Test latency (bolt button on the Nodes tab). Replace nodes that show Timeout. If every node times out, refresh the subscription; your provider may have changed servers, or your plan may have expired (see the expiry on the subscription card).
4. Open the Activity tab and tap the failing site’s connection. Outbound chain shows which node was used and Matched rule shows why. Use Route this domain to send it Direct or through the Proxy while you investigate.
5. Change the DNS mode (tap the DNS tile on Home to cycle it). Some apps behave differently with Fake-IP and Redir-Host.
6. Turn on Block QUIC (Traffic control) if video sites or browsers are slow or stall. QUIC runs over UDP, which some nodes and networks handle poorly; blocking it makes apps fall back to TCP.
7. Compare with Fast mode or the user-space TCP stack turned off (Network settings, one at a time, then reconnect). Both are recommended on, but this helps isolate rare compatibility issues. If turning one off fixes the problem, please report it.

Only one app is broken

• If you use HTTPS decryption, the app may pin its certificate. Remove its host from the decryption list. See FAQ.
• Try switching the DNS mode.
• On the Mac in system proxy mode, the app may ignore the system proxy. Use TUN mode, or for command-line tools use Copy terminal command.
• On the Mac with IPv6 set to Blackhole, apps that do not fall back to IPv4 (Telegram, for example) may fail. Set IPv6 to Off.
• On the Mac in TUN mode, local network addresses are deliberately excluded. Devices on your LAN are reached directly.

Connecting takes a long time

Things that make a connection start slowly, and what to do:

• The very first connection after installing or updating unpacks the built-in GeoIP / GeoSite data. This happens once.
• Rule sets your subscription needs but that are not downloaded yet are fetched before connecting, with a time limit of about 8 seconds. Rule sets that are already cached are used immediately even if they are out of date, and are refreshed in the background after connecting; the refreshed version takes effect on the next connection. If every first connection is slow, a rule-set URL in your subscription may be unreachable from your network. Look for warnings in the Engine logs.
• On the Mac in TUN mode, the panel shows “Tunnel starting (the first time it unpacks geo data and fetches rule providers, which can take a dozen seconds)”.
• If sites take a while to start loading after connecting, try Fake-IP mode, which avoids waiting for real DNS lookups.

Subscription refresh fails or times out

1. Read the error in the subscription card:
   • “Invalid subscription URL”: the link is malformed. Copy it again.
   • “Subscription is empty”: the server returned nothing.
   • “Subscription could not be parsed: …”: the server returned something that is not a valid Clash configuration. Often this is an error page (an expired or revoked link) or a different format.
   • A network error or timeout: the server could not be reached (continue below).
2. Open the URL in a browser on the same device. If it does not load there either, the server is unreachable from your network.
3. Try again disconnected (or in Direct mode). If refreshing only fails while connected, your rules are probably sending the provider’s domain through a node that cannot reach it. Add the subscription’s domain to the bypass list or create a Direct custom rule for it, then try again.
4. Check the format. MeowX needs a mihomo / Clash Meta YAML subscription. If your provider offers several formats, choose the Clash one. MeowX identifies itself with a mihomo-compatible User-Agent, so most providers send the right format automatically.
5. Signed in to a provider account? If the account card says Login expired, please sign in again, scan a new login code. Your subscriptions stay in place meanwhile.

Note

Refreshing always downloads a fresh copy; it never uses a cached response. If the nodes still look old after a successful refresh, the provider is serving the old list.

Mac: approvals and permissions

Symptom	Fix
“System proxy helper needs approval”	System Settings › General › Login Items & Extensions, turn on MeowX under Allow in the Background, then reconnect
“Helper not found”	Move MeowX.app to /Applications and open it from there
“Network extension needs approval”	Login Items & Extensions › Network Extensions (macOS 14: Privacy & Security), allow MeowX, then turn TUN mode on again
Screen QR scan finds nothing / fails	Grant Screen Recording in Privacy & Security, make sure the code is fully visible and not too small, then try again
Wi-Fi rules never match	MeowX needs Location Services permission to read Wi-Fi names. Without it, only the Other Wi-Fi rule applies. Use Open location settings on the Wi-Fi rules page

What to collect when asking for help

If you need to report a problem to your provider or to the MeowX team, gather the following.

1. Turn on Record logs (iPhone / iPad: the switch in the Me tab’s settings list; Mac: Settings › General › Record logs). Without it, only warnings and errors are recorded.
2. Reproduce the problem once.
3. Capture the logs.
   • iPhone / iPad: Activity › Logs. Use the MeowX and Engine source chips and the type chips to narrow down, then take screenshots of the relevant lines.
   • Mac: the Logs tab. Filter as needed and click Copy to put the filtered lines on the clipboard as text.
4. Capture the connection. For a site or app that fails, open its connection on the Activity / Connections tab and screenshot the Outbound chain and Matched rule.
5. Note the basics: device and OS version, the MeowX version and core version (Me › About, or the panel footer on Mac), the outbound mode, the DNS mode, and on Mac whether you use system proxy or TUN mode.
6. Screenshot any error card on Home and, on Mac, the System status section.
7. Turn Record logs off again afterwards.

Caution

Logs and connection lists contain the domains you visited and the names of your nodes. Review screenshots before sharing them publicly, and never share your subscription URL: it usually contains a personal token.

Logs live in memory only. They are cleared when you tap Clear, and lost when the app or the VPN extension restarts, so capture them before reconnecting.