Diagnostics

“I installed a module and nothing changed” usually has a simple cause: the host isn’t in the list, the certificate isn’t trusted, the app pins its certificate, or the server can’t be decrypted. Diagnostics shows what MeowX decided for each host and why.

The diagnostics page

Open Diagnostics from the HTTPS Decryption page (iOS) or the window’s sidebar (Mac).

• MeowX keeps the most recent 500 decisions, grouped by host and reason with a count. Only the hostname, port and result are recorded, never paths or query strings, and only in memory.
• Filter by Problems, Decrypted normally or All, and search by host. Counters at the top summarize decrypted, passed-through and failed connections.
• Each host shows its latest result, an explanation, a suggestion and, where useful, a button such as Add exclusion, Skip upstream certificate verification…, View request records, View connections or Trust certificate.
• Many entries add a specific detail, such as “Specific: server sent alert 40 (handshake_failure)”. When a host is currently being skipped, the page shows the handshake failure that caused it (“Last handshake failure: …”).
• Clear temporary skips empties both the certificate-pinning skip list and the server-failure skip list, so those hosts are tried again right away.

The same results appear in the hostname list next to each entry, and in connection details as the HTTPS Decryption row.

Result categories

Result	Meaning
Decrypted	Decrypted and processed by your modules and local rules.
Decrypted · issue	Decrypted, but something about this connection was unusual.
Decrypted · preparing	Not decrypted yet: QUIC was blocked so the app falls back to TCP, which will be decrypted. Not a problem.
Passthrough	Forwarded unchanged; the app works as if decryption were off.
Not connected	The app rejected the certificate or the connection was dropped; this attempt failed.

Reasons

Reasons marked ⚠ need your attention and are highlighted.

Passed through

Reason	What it means	What to do
Hostname mismatch ⚠	When the connection opened, its domain matched the list, but the hostname in the app’s TLS handshake didn’t. Usually the domain is a CNAME to another name, or the app connected by IP.	Look up the actual hostname in request records or the connection list and add it too.
App uses HTTP/2 only, server doesn’t	The app accepts only HTTP/2 (gRPC, some SDKs) but the server only speaks HTTP/1.1. MeowX doesn’t convert between the two, so the connection is passed through.	Can’t be decrypted for now. Apps using HTTP/1.1 with the same server are decrypted normally.
App supports only TLS 1.2	The app only speaks TLS 1.2; MeowX decrypts TLS 1.3 only.	Can’t be decrypted for now.
No hostname	The handshake carried no hostname, or the app connected by IP, so no certificate can be issued.	Can’t be decrypted; adding the IP doesn’t help.
TLS handshake not received	No complete TLS handshake arrived within 300–500 ms. Usually not HTTPS at all (games, mail and other protocols where the server speaks first).	Give the hostname an explicit port (such as :443) so the bare name doesn’t cover other ports.
Unsupported handshake parameters	The app uses a key exchange or signature algorithm MeowX doesn’t support.	Can’t be decrypted.
Server supports only TLS 1.2	The server supports only TLS 1.2 (or older). Passed through, and not retried for 10 minutes.	Can’t be decrypted for now. Ad hosts answered entirely locally aren’t affected.
Incompatible encryption	The server doesn’t accept the key exchange or cipher MeowX offers (it only supports an unusual curve, or actually only supports TLS 1.2). Not retried for 10 minutes.	Can’t be decrypted for now; add an exclusion if you don’t want it retried.
Server handshake error	The handshake with the server failed (the server disconnected, sent invalid data, or a signature check failed). Not retried for 10 minutes.	Ignore occasional ones; add an exclusion if it keeps happening.
Handshake with server failed	Same as above, recorded by an older version of MeowX without a more specific reason.	Add an exclusion if you don’t want it retried.
Server rejects the app’s HTTP version	The server refused every HTTP version the app offered during the handshake. If both HTTP/2 and HTTP/1.1 were refused, it isn’t retried for 10 minutes.	Usually nothing; add an exclusion if it keeps happening.
Server certificate not trusted ⚠	The server’s certificate failed verification (self-signed, missing intermediate certificate). Passed through so the app can decide for itself.	Add an exclusion. When debugging your own service, you can turn on Skip upstream certificate verification.
Server requires a client certificate	Mutual TLS (mTLS) services can’t be decrypted.	Add an exclusion.
Server connection timed out	The handshake timed out or a network error occurred. Passed through this once, and not added to the skip list.	Nothing; retried next time.
Certificate pinning, temporarily skipped ⚠	This host rejected MeowX’s certificate several times recently, so it is passed through for 1 hour.	Add an exclusion. If the app actually works and this is a false alarm, turn off Automatically skip certificate pinning in Advanced.
Server error, temporarily skipped	A recent handshake with this server failed, so it is passed through for 10 minutes.	Wait for it to expire, or clear temporary skips.
Too many decrypted connections ⚠	The limit on simultaneous decrypted connections or memory was reached; new connections are passed through.	Trim the hostname list; don’t use *.
LAN device	The connection came from another device through the local proxy with LAN access enabled. Those devices don’t have this certificate.	LAN devices aren’t decrypted.
Always direct	Your provider’s dashboard and subscription domains, the bypass list and APNs always connect directly and are never decrypted, whatever modules say.	Nothing.
Certificate not trusted ⚠	The certificate isn’t installed or full trust is off, so HTTPS isn’t decrypted.	Trust the certificate.
Handshake doesn’t announce HTTP	The app announced an application protocol that is neither HTTP/2 nor HTTP/1.1 (MQTT, DNS over TLS, mail).	Can’t be decrypted; add an exclusion to hide it.

Decrypted, with an issue

Reason	What it means	What to do
Not HTTP	After decrypting, the traffic turned out not to be HTTP (a private protocol, MQTT, mail). It is relayed unchanged, without rewriting.	Add an exclusion to save the decryption overhead.
Suspected certificate pinning ⚠	The handshake succeeded, but the app sent no request and closed the connection within 1 second. This is only a hint; the host is not skipped automatically.	Add an exclusion if pages or features misbehave.
Server rejected the request ⚠	After decryption the server answered with 403 or a challenge page; it may have recognized MeowX by its TLS fingerprint.	Add an exclusion.
Cross-host rewrite not supported	The connection was decrypted, but a rule tried to transparently rewrite the request to another host. That rule was not applied; the request went to the original address.	Not supported yet; use a 302 redirect instead.

Preparing

Reason	What it means	What to do
QUIC blocked	QUIC was blocked so the app falls back to TCP, where it can be decrypted. When an app uses QUIC directly by IP, the decision is based on the hostname in the QUIC handshake.	Nothing. If the app never falls back and can’t connect, add an exclusion.

Not connected

Reason	What it means	What to do
App rejected the certificate ⚠	The app explicitly refused MeowX’s certificate during the handshake, so this attempt failed. Usually certificate pinning, or an app that doesn’t accept user-installed certificates.	Add an exclusion.
Disconnected during handshake ⚠	The app closed the connection right after receiving the certificate. This is how the system networking library rejects a certificate, but it can also mean the user cancelled.	Add an exclusion if it keeps happening.
Too much 0-RTT data	Before the handshake finished, the app sent more early data than MeowX buffers, so the connection was closed. The app reconnects.	Usually nothing; add an exclusion if it keeps happening.

If the tunnel is newer than the app, you may see Unknown reason with the internal code; update the app to see an explanation.

Certificate pinning

Apps that pin their certificate accept only their own server’s certificate, so decrypting them breaks them. Neither MeowX nor any other tool can get around pinning. MeowX detects it and steps aside:

• Strong signals: the app rejects the certificate with a TLS alert (bad certificate, certificate unknown or unknown CA), or closes the connection without an alert within 1 second of MeowX sending its certificate. Apps using the system networking library reject certificates in the second way.
• Automatic skip: two strong signals for the same host within 5 minutes put it on the pinning skip list, and it is passed through for 1 hour. This is controlled by Automatically skip certificate pinning in Advanced (on by default).
• Weak signal: a successful handshake followed by no request and a close within 1 second only shows Suspected certificate pinning. It never skips the host automatically, because browsers’ pre-connections behave the same way.
• The skip list is per host. On the Mac, a process that doesn’t trust the certificate (a root service, or a command-line tool) can trigger it for that host for all apps; turn off automatic skipping if that’s a problem.
• The hostname list marks hosts with a pinning result and offers Add exclusion. An exclusion is the permanent fix.

QUIC and HTTP/3

QUIC (HTTP/3) runs over UDP and can’t be decrypted. For hosts that would be decrypted (in the list, certificate trusted, not skipped, from this device, not always-direct), MeowX blocks QUIC on UDP port 443 so the app falls back to TCP:

• When the hostname is known (from MeowX’s DNS), QUIC to it is blocked.
• When an app connects by IP without a known hostname, MeowX reads the hostname from the first QUIC packets (QUIC versions 1 and 2, up to 3 packets). If that host would be decrypted, the connection is blocked and diagnostics records QUIC blocked. Packets are never held back, so QUIC to other hosts isn’t slowed down.
• For the same hosts, MeowX answers DNS HTTPS / SVCB queries with empty results, so apps don’t learn about HTTP/3 or ECH for them, and it removes Alt-Svc headers from decrypted responses.

This is separate from the general Block QUIC setting, which blocks all UDP 443 traffic. Some apps never fall back to TCP when QUIC is blocked; add an exclusion for those.

HTTP/2 and HTTP/1.1

MeowX mirrors the app’s protocol choice:

1. It connects to the server first and offers the HTTP versions the app offered (only HTTP/2 and HTTP/1.1, in the app’s order).
2. Whatever the server picks, MeowX picks the same with the app. If both sides speak HTTP/2, requests are handled per stream over one connection; otherwise HTTP/1.1 is used.

App offers	Server answers	Result
No protocol list	(none sent)	HTTP/1.1
HTTP/2 and/or HTTP/1.1	HTTP/2	HTTP/2
HTTP/2 and/or HTTP/1.1	HTTP/1.1	HTTP/1.1
Includes HTTP/1.1	No protocol	HTTP/1.1
HTTP/2 only	No protocol (server is HTTP/1.1 only)	Passed through: App uses HTTP/2 only, server doesn’t
HTTP/2 and/or HTTP/1.1	Refuses	Passed through: Server rejects the app’s HTTP version
Only other protocols	—	Passed through: Handshake doesn’t announce HTTP

MeowX doesn’t convert between HTTP/2 and HTTP/1.1. WebSocket over HTTP/2 isn’t offered, so browsers open a separate HTTP/1.1 connection for WebSocket; after the upgrade, WebSocket data is relayed unchanged. Hosts answered entirely locally use HTTP/1.1 when the app offers it, and HTTP/2 otherwise.

TLS requirements

From the app (client):

• TLS 1.3, with a hostname (SNI) that isn’t an IP address.
• An X25519 or P-256 key share, and support for ECDSA P-256 signatures. Common system libraries and browsers meet this.
• An application protocol list that includes HTTP/2 or HTTP/1.1, or none at all.

Real ECH connections use an outer hostname that doesn’t match the list and are passed through. “GREASE” ECH that browsers send without real ECH is ignored, and those connections are decrypted normally.

From the server (upstream):

• TLS 1.3. MeowX offers X25519, P-256 and P-384 (P-384 through a retry).
• A certificate that passes verification against the system’s trusted roots. MeowX doesn’t download missing intermediate certificates, so a server that doesn’t send its full chain may fail verification even though browsers accept it. On the Mac in TUN mode, verification happens in the system extension, so CAs you trust only in your login keychain don’t count.
• No client certificate requirement.

Every failure on the server side happens before the app has received anything, so it always falls back to passthrough; most failures also put the host on the 10-minute server-failure skip list (timeouts and network errors don’t).

Skip upstream certificate verification

This Advanced setting makes MeowX accept forged server certificates and re-sign them with the certificate your device trusts, which vouches for a man in the middle on someone else’s behalf. Turn it on only while debugging your own services. Modules can’t turn it on.

TLS fingerprint

When MeowX connects to the server, it uses its own TLS handshake rather than the app’s. Sites that use TLS fingerprints for bot detection may then answer with a 403 or a challenge page even though the app works without decryption. MeowX records this as Server rejected the request; exclude the host to fix it.