Doctor

The Doctor answers “why isn’t my traffic showing?” It checks the macOS proxy, the certificate, your VPN, the app’s own switches and every recent connection, then explains per app or device what is stopping its requests from showing or making them fail. Each problem comes with the evidence (hosts, counts, times) and one button that fixes it.

1234

Problems grouped by app, each with its evidence and a fix.

1. Problems, or the log of every connection
2. One fix per problem
3. The pinned hosts
4. What was checked and is fine

×

Open the Doctor

Where	What it shows
Tools › Doctor…	Everything, or the app selected in the sidebar
The stethoscope in the bottom bar	Everything. A red number next to it counts the problems found
Right-click an app in the sidebar › Why isn’t app showing traffic?	That app
Right-click a device in the sidebar › Why isn’t this device showing traffic?	That device
Right-click an app under Not using the proxy	That app
Why? next to a failed request’s error in the inspector	The app that sent it

Cloak Proxy runs the checks every 20 seconds in the background, so the count in the bottom bar stays current. The window checks again when it opens. Click the arrow button to check now.

At the top of the window, choose Everything or one app or device. Diagnosing one app also tells you when nothing is wrong: App’s traffic is showing, with how many requests it sent and when the last one was, or Cloak Proxy hasn’t seen the app connect.

Read a finding

Findings are grouped under the app, the device, or This Mac.

Part	Meaning
Red octagon	A problem: it stops traffic from showing or makes it fail. These are what the bottom bar counts.
Orange triangle	A warning: something you probably turned on yourself, such as paused recording or a filter.
Gray circle	A note, for example that a VPN is connected but traffic still arrives.
Gray chips	The hosts involved. Click more to see them all.
The last line	The evidence: how many connections or requests, the TLS alert, addresses, and when it last happened.
The button	The fix. Learn more opens the matching section of this page.

Below the findings, Checked lists what was checked and is fine, for example “The macOS proxy points at Cloak Proxy (127.0.0.1:9090).” or, from 0.5.0, “The network extension captures curl.” New in 0.5.0 When nothing is wrong, the window says Nothing is blocking traffic.

What the Doctor checks

Finding	How it’s detected	Fix button
Cloak Proxy isn’t listening	The proxy couldn’t open its port.	Change the port (Settings › Network)
The macOS proxy is off	macOS sends HTTP and HTTPS nowhere. A warning when you turned it off, a problem (Something turned the macOS proxy off) when Cloak Proxy had turned it on.	Turn on macOS proxy
The macOS proxy points at host:port	Another proxy is set. If an app on this Mac listens on that port, the Doctor names it.	Point it at Cloak Proxy
A proxy auto-config file decides where traffic goes	A PAC file is set instead of a fixed proxy.	Point it at Cloak Proxy
VPN overrides the macOS proxy	A VPN is connected or carries the default route, and the macOS proxy no longer points at Cloak Proxy. See VPNs.	Set the proxy again
Recording is paused	Requests go through but aren’t added to the list. From 0.4.2, traffic passes through untouched by default (no decryption, no rules), and the evidence counts the connections that did; with Keep intercepting, just don’t record it says requests are still decrypted with your rules.	Resume recording
The filter hides every request	Requests are captured, but the filter, a content chip or the sidebar selection hides all of them. When you diagnose one app: The filter hides N of app**’s requests**.	Clear filters
App is muted	Its requests went through Cloak Proxy recently and weren’t recorded.	Unmute
The Allow List skips N requests	Requests that matched no Allow List rule, with their hosts.	Turn off the Allow List
The Cloak Proxy certificate isn’t trusted on this Mac	The root certificate isn’t trusted in the login keychain. A problem when anything is set to be decrypted or apps refused the certificate.	Trust the certificate
App skips the proxy	The app has direct connections to the internet (the same check as Not using the proxy in the sidebar).	Capture its domains. From 0.5.0, with the Cloak Proxy download: Capture all its traffic (App Capture) New in 0.5.0
App still skips the proxy for some servers	A captured app also connects directly to servers outside its captured domains.	Add its domains
App skips the proxy, and app capture is off New in 0.5.0	The app is picked in App Capture, but the extension isn’t capturing, so its connections still go straight out.	Turn on app capture
The network extension is waiting for your approval in System Settings (or App capture is off, App capture stopped) New in 0.5.0	App Capture is wanted with apps picked, but macOS hasn’t allowed the extension yet, Cloak Proxy isn’t in Applications, or the extension stopped. Under This Mac.	Open System Settings or Open app capture
App uses HTTP/3, which no proxy can see	The app holds QUIC sockets. See HTTP/3.	Capture its domains. From 0.5.0, with the Cloak Proxy download: Capture all its traffic (App Capture blocks its QUIC so it falls back to TCP) New in 0.5.0
App pins certificates for N hosts	The app refuses Cloak Proxy’s certificate for some hosts while it’s trusted. See Certificate pinning.	Stop decrypting these hosts
Host answers with a bot challenge (or N sites) Since 0.4.2	A decrypted request got Cloudflare’s challenge: a 403 or 503 with cf-mitigated: challenge, or server: cloudflare with the challenge page. See Bot challenges and sign-ins.	Stop decrypting the host
Signing in through host fails while it’s decrypted Since 0.4.2	A decrypted sign-in was refused: Google’s “This browser or app may not be secure” page, or 403s, 429s, timeouts or resets on a sign-in page. See Bot challenges and sign-ins.	Stop decrypting the host
App doesn’t trust the Cloak Proxy certificate	The app refuses the certificate on every host (at least three, or with an “unknown CA” alert) although macOS trusts it. Firefox, Java, Node.js, Python and Docker keep their own list of trusted certificates.	Set up app (Device & Runtime Setup)
Device doesn’t trust the Cloak Proxy certificate	A device refused the certificate, or Cloak Proxy stopped decrypting for it after it refused three handshakes.	Set up the certificate (iPhone & iPad, certificate step)
Device hasn’t connected	A device you named has sent nothing this session.	Set up the device
No requests from device lately	A device that sent traffic before has sent nothing for 15 minutes. Its Wi-Fi proxy may point elsewhere now, or it’s on another network.	Check the device setup
Other devices can’t connect	Cloak Proxy only listens on this Mac, and devices have used it before.	Allow other devices (restarts the proxy)
App**’s requests to** host fail	At least two connections or requests to a server failed in the last 30 minutes: DNS, refused, timed out, reset, unreachable, or the server’s TLS.	Show connections
The upstream proxy wants a username and password (or refuses connections) Since 0.4.2	The external proxy in Settings › Network answered 407, 403 or a SOCKS5 refusal for connections in the last 30 minutes. See Upstream proxy.	Check the upstream proxy (Settings › Network)
Looked up, but never connected	See Looked up, but never connected.	None

Connection evidence comes from the last 30 minutes.

Certificate pinning

An app that pins certificates only accepts its own server’s certificate, not the one Cloak Proxy makes for that host. When Cloak Proxy decrypts such a host, the app refuses the connection, and its requests fail. No proxy can decrypt a pinned connection without changing the app.

The Doctor reports pinning when an app refuses Cloak Proxy’s certificate for the same host at least twice, never accepts it for that host, and the certificate is otherwise trusted: the app accepted it for other hosts, or macOS trusts it. It recognizes both ways apps refuse:

• A TLS alert during the handshake, such as “bad certificate” or “certificate unknown”. The alert is shown in the evidence.
• A finished handshake followed by the app closing the connection within 1.5 seconds without sending anything. OkHttp and many SDKs check their pins after the handshake. Browsers’ unused connections stay open longer, so they aren’t counted.

An “unknown CA” alert means the app doesn’t trust the certificate at all, which the Doctor reports separately.

Stop decrypting these hosts makes the app work again. A host listed exactly in SSL Proxying is removed from it. A host covered some other way (a wildcard such as *.example.com, SSL Proxying for the whole app, or a captured domain) is added to Never decrypted in Settings › SSL Proxying. Its connections then pass through encrypted and show as tunnels. Click Decrypt again there to undo it.

Caution

To read a pinned app’s traffic, turn pinning off in a debug build of your own app. Don’t try to defeat pinning in apps you don’t own or aren’t authorized to test.

Bot challenges and sign-ins

Since 0.4.2

Sites behind Cloudflare’s bot protection, and the sign-in pages of Google, Microsoft, Okta and others, check that a connection comes from a real browser by its TLS and HTTP/2 fingerprint. When Cloak Proxy decrypts a connection it talks to the server with its own fingerprint, so these refuse it: Cloudflare answers 403 with a “Verify you are human” check that never passes, and Google says This browser or app may not be secure or the sign-in hangs.

From 0.4.2, the Doctor reports:

• A bot challenge when a decrypted request got Cloudflare’s challenge page: the cf-mitigated: challenge header Cloudflare puts on every challenge, or a 403, 429 or 503 from server: cloudflare whose page loads the challenge platform. One is enough.
• A failing sign-in when a decrypted sign-in page was refused: Google’s “This browser or app may not be secure” page (or a redirect to it) is enough on its own, and so is one 403, 429, timeout or reset on a built-in sign-in host you chose to Decrypt anyway. Elsewhere it takes two refusals on a page the browser opened on a sign-in host or path (login., sso., /signin, /oauth2/…), so one wrong password isn’t reported. API calls to auth endpoints don’t count.

The evidence says why each host is decrypted: Decrypt anyway for a built-in sign-in host, the browser being in SSL Proxying › Apps, or the SSL Proxying rule that covers it. For a browser it suggests the Capturing Browser instead.

Stop decrypting the host turns Decrypt anyway back off for a built-in sign-in host, removes a host listed exactly in SSL Proxying, or adds it to Never decrypted in Settings › SSL Proxying when a wildcard or the browser’s own rule covers it. Its open decrypted connections close once their requests in flight finish, so the browser reconnects through an encrypted tunnel: reload the page or sign in again.

In 0.4.1 and earlier the Doctor doesn’t report these. If a sign-in or a Cloudflare-protected site fails while its browser or host is decrypted, turn SSL Proxying off for it. See Decrypting a browser.

HTTP/3

HTTP/3 travels over QUIC, on UDP port 443. HTTP proxies only carry TCP, so no proxy, including Cloak Proxy, can see HTTP/3 requests. Most apps don’t use HTTP/3 while a proxy is set, but apps with their own QUIC code can.

The Doctor finds these apps by looking at each app’s sockets: an app with UDP sockets connected to port 443 of a public address (seen in two checks within 5 minutes) is listed with those addresses. It also notes when a server offered HTTP/3 in an Alt-Svc response header and the app then stopped sending it requests through Cloak Proxy for 2 minutes while still using other servers: App may have switched to HTTP/3.

Capture its domains opens the capture sheet. Captured domains resolve to Cloak Proxy, which doesn’t accept QUIC, so most apps fall back to HTTPS over TCP within a moment and their requests show up. An app that only speaks HTTP/3 stays hidden.

New in 0.5.0 From 0.5.0, with App Capture, the network extension refuses the picked apps’ QUIC connections (Block HTTP/3 for these apps, on by default) and sends the HTTPS they fall back to through Cloak Proxy, without capturing any domains.

VPNs

VPN apps such as Surfshark and PureVPN can change where traffic goes. The Doctor reads which VPNs macOS reports as connected and which network carries the default route.

Situation	What the Doctor says
A VPN is connected and the macOS proxy still points at Cloak Proxy	A note. Apps still send traffic to Cloak Proxy, which reaches servers through the VPN. If requests stop arriving, turn off the VPN’s options that block the local network or route around local proxies, or disconnect it while you capture.
A VPN is connected or carries all traffic, and the macOS proxy no longer points at Cloak Proxy	A problem: the VPN is the active network and has no proxy set. Click Set the proxy again. If it doesn’t stick, disconnect the VPN while you capture.

Looked up, but never connected

For a captured app, the Doctor compares the lookups Cloak Proxy answered with the connections that arrived. A captured host looked up at least three times without any connection on port 443 or 80 is listed. The app may use another port (gRPC often uses 50051), which capture doesn’t cover, or HTTP/3 only.

Upstream proxy

Since 0.4.2

With an external proxy set, Cloak Proxy 0.4.2 sends every connection it opens through it. When the proxy refuses, those requests and tunnels fail, so the Doctor reports it for this computer, with the hosts and the proxy’s answer:

Answer	What to do
407 Proxy Authentication Required, or a SOCKS5 proxy that wants or refuses credentials	Enter the username and password the proxy expects in Settings › Network, or correct them.
403 Forbidden or another refusal	The proxy’s rules block those hosts. If they’re reachable without it, add them to Don’t use it for; otherwise ask whoever runs the proxy.

Check the upstream proxy opens Settings › Network. A proxy that doesn’t answer at all shows as an ordinary connection failure (Connection refused, Timed out) on the requests instead.

Connections

The Connections view lists every recent connection to Cloak Proxy, newest first, including connections that failed before they became a request: a refused certificate, a server that can’t be reached, a host that doesn’t resolve.

123

Every connection with its timings, including ones that never became a request.

1. Filter by host, app or failure
2. Handshake time, TLS version and ALPN
3. How the connection ended

×

Column	Shows
Time	When the connection opened
App	The app or device that opened it
Host	Where it went, with the port when it isn’t 80 or 443
Kind	HTTP, Tunnel (HTTPS passed through), Decrypted, SOCKS, Captured (by DNS capture) or Reverse proxy; from 0.5.0 also App capture, App capture, decrypted or App capture, raw TCP for connections from App Capture New in 0.5.0
Connect	Time to connect to the server, including its DNS lookup, for tunnels Cloak Proxy relays; for other connections, the DNS lookup before the first request (<1 ms when the answer was cached)
TLS	For decrypted connections: the handshake with the app, the TLS version and the protocol agreed by ALPN (h2 or http/1.1)
Requests	Requests sent on the connection
Result	Open, Closed, Not recorded: and why, or the failure: DNS lookup failed, Connection refused, Timed out, Connection reset, Network unreachable, Server TLS failed, Certificate rejected (with the TLS alert), Closed during handshake or Closed after handshake

Type in the field to filter by host, app or failure, and check Failed only to see just the failures. Select a row to read the full error below the table. Show connections on a finding filters the view to that app; click the cross on its name to show every app.

Cloak Proxy keeps the newest 4,000 connections and the timings of the newest 20,000 requests in memory, and drops the oldest first. The log isn’t saved with sessions.

The Connection section in the inspector

The request’s Summary tab, and the panel for an encrypted tunnel, end with a Connection section: the connection’s kind and number, Connect, TLS with the app (time, version and ALPN), the TLS alert if the app refused the certificate, Requests on it (and how many weren’t recorded, with the reason), and the Failure. For the request itself it adds DNS, Server (time from sending the request on to the response) or Server failure, and HTTP/3 when the server offered it. A failed request has a Why did this fail? link that opens the Doctor for its app. See Inspector.

The section appears for requests captured in this run while their connection is still in the log. Imported sessions don’t have one.

Note

For decrypted requests, Cloak Proxy’s connection to the server is shared between requests, so the inspector shows the time to the response rather than the server’s own connect and TLS times.

Ask your AI assistant

The diagnose_capture tool in Cloak Proxy’s MCP server returns the same findings as JSON, each with its kind, severity, explanation, hosts, evidence and suggested fix, plus the checks that passed and recent failed connections. Pass app to diagnose one app or device. The control API serves it as the diagnose_capture method of POST /api/rpc. See MCP tools reference.

Terminal

cloakctl mcp   # then ask: "Why isn't ShopApp's traffic showing in Cloak Proxy?"

What the Doctor can’t see

• Traffic that never reaches this Mac, such as a phone on another network.
• Which proxy a device’s Wi-Fi settings point at. The Doctor only knows that a device stopped sending requests.
• Raw TCP on ports other than 80 and 443, and UDP other than QUIC on port 443.
• The macOS proxy and VPN checks don’t run in test mode (CLOAK_SNAPSHOT), which never touches the macOS proxy.

Related

Apps that ignore the proxyCapture apps that connect straight to the internet.

SSL ProxyingChoose which hosts and apps are decrypted.

TroubleshootingCommon problems, their causes and fixes.

Failed requests and tunnelsWhat failed rows and encrypted tunnels mean.