Troubleshooting

Most problems with a debugging proxy come down to three questions: is the traffic reaching Cloak Proxy, can Cloak Proxy decrypt it, and can Cloak Proxy reach the server. This page starts with where to look, then goes through each problem with its cause and fix.

Start here

Read the capture status

The middle of the main window’s toolbar shows the proxy’s state and address, for example Capturing · 127.0.0.1:9090. Hover over it for details.

State	Color	Meaning
Capturing	Green	Listening, recording, and the macOS proxy points at Cloak Proxy.
Listening	Yellow	Listening and recording, but the macOS proxy is off. Only apps and devices you point at Cloak Proxy yourself are captured.
Paused	Orange	Recording is paused. Traffic still flows but isn’t added to the list.
Not listening	Red	The proxy couldn’t start. Hover to see why, for example a port in use.

The status bar at the bottom of the window adds macOS traffic: On or macOS traffic: Off. Click to capture (click it to switch), the debugging tools that are on, the request count, and CA trusted or CA not trusted for the certificate.

Check the log

Cloak Proxy writes diagnostics, not traffic, to:

~/Library/Logs/CloakProxy/cloak-proxy.log

It records each start (port, macOS proxy and certificate state), every change to the macOS proxy, proxy guard events, refused device connections, hosts that pin their certificates, and listener errors. Open it with:

Terminal

open -a Console ~/Library/Logs/CloakProxy/cloak-proxy.log

No traffic appears

The list shows Waiting for traffic, or an app you’re using is missing.

Cause	Fix
The macOS proxy is off.	Click Capture macOS Traffic in the empty list, click macOS traffic: Off. Click to capture in the status bar, or press ⇧ ⌘ P. See macOS traffic.
Recording is paused.	Press ⇧ ⌘ R or choose Proxy › Resume Recording.
A filter or sidebar selection hides it.	Select All Traffic in the sidebar and clear the filter field and content chips. See Filtering.
Allow List is on.	Only requests matching an Allow List rule are recorded. Turn it off in Tools, or add a rule. See Allow List.
The host is on the Bypass list.	macOS sends it straight to the internet. Remove it in Settings › Bypass, then turn the macOS proxy off and on.
A VPN or configuration profile overrides proxy settings.	Cloak Proxy warns that macOS doesn’t report the proxy as active. Disconnect the VPN, or capture the app another way (below).
The app ignores the macOS proxy.	It appears under Not Using the Proxy in the sidebar. See Apps that ignore the proxy.
A command-line tool doesn’t use the macOS proxy.	Terminal programs read http_proxy and similar variables instead. Use Open Configured Terminal in Device & Runtime Setup. See Terminal and runtimes.

HTTPS shows as locked tunnels

Requests show only a host with a lock, and the inspector says Encrypted HTTPS to the host: “Cloak Proxy passed this connection through without reading it.”

123

An HTTPS connection Cloak Proxy didn't decrypt, with one-click fixes.

1. Cloak Proxy passed this connection through without decrypting it
2. Decrypt this host from now on
3. Decrypt everything from the app that made the connection

×

That’s expected. Cloak Proxy only decrypts hosts and apps you choose. To decrypt:

1. Make sure the certificate is trusted (see the next section). The buttons are dimmed until it is.

2. Click Enable only the host in the inspector, or Enable all domains from the app. You can also right-click a domain or app in the sidebar, or add a pattern in Settings › SSL Proxying.

3. Use the app again. Cloak Proxy closes the host’s open tunnels so the app reconnects, decrypted.

See SSL proxying.

The certificate isn’t trusted

An orange banner says Trust the Cloak Proxy certificate to decrypt HTTPS, the status bar shows CA not trusted, or decrypted requests fail.

Situation	Fix
Never installed on this Mac	Click Install & Trust… in the banner or in Settings › Certificate. macOS asks for your password.
Installed but the status still says Not trusted	Click Check Again in Settings › Certificate. If it stays untrusted, click Re-install.
After Regenerate Certificate…	Install the new certificate on this Mac and on every device and simulator again.
A browser or runtime with its own trust store (Firefox, Java, Node.js, Python)	Give it the certificate separately. See Java, Firefox, Docker, Flutter and Electron and Terminal and runtimes.

A failed request whose message starts with “TLS handshake with the client failed. The client probably doesn’t trust the Cloak Proxy CA, or it pins certificates.” means the app refused Cloak Proxy’s certificate. If the app should trust it, fix trust as above. If it pins certificates, see Apps that pin certificates. See Certificate.

The internet stops working

After Cloak Proxy quit unexpectedly

While macOS traffic is captured, the system proxy points at Cloak Proxy. If Cloak Proxy stopped without cleaning up, apps would have nowhere to send traffic. Cloak Proxy guards against this:

• Quitting normally, kill, Control C in a terminal or closing the terminal it runs in all restore your previous proxy settings before it exits.
• A small helper, the proxy guard (cloakctl proxy-guard), watches the app while the macOS proxy is on. If the app disappears (Force Quit, a crash, a forced restart), it restores your previous settings within a few seconds, unless Cloak Proxy is already listening again. The log says “the proxy guard restored it”.

If you’re still offline:

1. Open Cloak Proxy and quit it with ⌘ Q. It restores the settings it saved.

2. If that doesn’t help, open System Settings › Network, choose your connection (for example Wi-Fi), click Details…, open Proxies, and turn off Web proxy (HTTP) and Secure web proxy (HTTPS).

   Or in Terminal, for Wi-Fi:

   Terminal

   networksetup -setwebproxystate "Wi-Fi" off
   networksetup -setsecurewebproxystate "Wi-Fi" off

3. Check the log. “Couldn’t start the proxy guard” or “No cloakctl next to the app” means the guard wasn’t running; reinstall Cloak Proxy so cloakctl is back inside the app.

On a phone or another device

A device whose Wi-Fi proxy points at your Mac can’t reach the internet while Cloak Proxy isn’t running or the Mac is asleep or on another network. Turn the proxy Off on the device, or open Cloak Proxy again. For Android over adb, click Disconnect Proxy.

Port 9090 is in use

The toolbar shows Not listening, and hovering over it shows Couldn't listen on port 9090: … Address already in use.

1. Find what’s using the port:

   Terminal

   lsof -nP -iTCP:9090 -sTCP:LISTEN

2. If it’s another Cloak Proxy (a second copy of the app, or cloakctl run), stop it. After you quit and reopen the app, it waits a few seconds for the old copy to free the port.

3. Otherwise, choose another port in Settings › General › Port, such as 9091, and click Apply & Restart Proxy. Update any device or runtime that points at the old port.

The same applies to the SOCKS5 proxy and Reverse proxies ports on Settings › Network; their errors appear next to Apply & Restart Proxy there.

macOS won’t open the app the first time

macOS may say it can’t verify the developer. Open it once by hand:

1. Try to open Cloak Proxy, then dismiss the warning.

2. Open System Settings › Privacy & Security, scroll to Security, and click Open Anyway next to the message about Cloak Proxy.

3. Confirm, and enter your password if asked. Later launches open normally.

See Install.

Apps that ignore the proxy

Some apps and SDKs (some Electron apps, Firebase and gRPC clients, apps using raw sockets) connect straight to the internet. Cloak Proxy notices and lists them under Not Using the Proxy in the sidebar, with their direct connections.

Option	When to use it
The capture sheet	Click the app under Not Using the Proxy. Cloak Proxy suggests its domains and points them at itself through /etc/resolver. macOS asks for your password. See Apps that ignore the proxy.
A reverse proxy	When you can change the app’s server URL: point it at http://localhost:PORT and set the target in Settings › Network › Reverse proxies.
Environment variables	Command-line tools: see Terminal and runtimes.

Captured domains apply to every app on the Mac that uses them, and keep resolving while Cloak Proxy is closed, through a small background helper. Click Stop Capturing in the capture sheet to remove them.

Apps that pin certificates

Some apps only accept their server’s real certificate. Cloak Proxy can’t decrypt them, and you’ll see the “TLS handshake with the client failed” message, followed by the app failing to connect while the host is on your SSL Proxying list.

• Remove the host or app from SSL proxying so its traffic passes through encrypted again.
• For a domain captured through the capture sheet, Cloak Proxy does this for you: it passes the pinned host through so the app keeps working, and the sheet lists it as Pinned (passed through).
• For your own app, turn off pinning in debug builds. Don’t try to defeat pinning in apps you don’t own or aren’t authorized to test.

Other devices can’t connect

Cause	Fix
Allow other devices to connect is off.	Turn it on in Settings › General and click Apply & Restart Proxy, or click Allow Other Devices to Connect in the iPhone & iPad setup.
The device’s address isn’t on Allowed devices.	Add it in Settings › Network, or empty the list. The log shows “Refused a connection from … not in the allowed client list”.
Wrong address or port on the device	Use the address shown as This Mac’s address in Settings › General, for example 192.168.1.20:9090.
The device is on a different network	Put both on the same Wi-Fi. Guest networks often block devices from reaching each other.
The certificate page doesn’t load	http://cloak.proxy only works once the device’s proxy points at Cloak Proxy. You can also scan the QR code in iPhone & iPad setup.

See Other devices and access control.

iPhone and iPad

Symptom	Fix
No traffic	In Settings › Wi-Fi, tap ⓘ next to your network, choose Configure Proxy › Manual, and enter your Mac’s address and port.
HTTPS fails in every app	Installing the profile isn’t enough. Also turn on full trust in Settings › General › About › Certificate Trust Settings for Cloak Proxy CA.
HTTPS fails after regenerating the certificate	Delete the old profile in Settings › General › VPN & Device Management and install the new one.
One app fails, others work	It may pin certificates. See Apps that pin certificates.

When you’re done, remove the profile and set the Wi-Fi proxy back to Off. See iPhone and iPad.

For the iOS Simulator: simulators use the Mac’s proxy, so turn on macOS capture, then click Install Certificate on All Booted Simulators and restart the app in the simulator. This needs Xcode; if Cloak Proxy says simctl isn’t installed, install Xcode and run sudo xcode-select -s /Applications/Xcode.app. See iOS Simulator.

Android

Symptom	Fix
The one-click buttons are missing	Cloak Proxy says adb wasn’t found. Install Android platform tools, for example brew install android-platform-tools.
No traffic	Click Connect Proxy. It runs adb reverse and sets the device’s proxy to 127.0.0.1 on your port. Click Show Connected Devices to check the device is listed.
HTTPS fails in your app	Apps targeting Android 7 or later ignore user-installed certificates unless their network security config trusts them. Add a debug-overrides block that trusts user certificates to your debug build.
The certificate isn’t installed	Click Push Certificate, then on the device go to Settings › Security › Encryption & credentials › Install a certificate › CA certificate.
The device has no internet after debugging	Click Disconnect Proxy.

See Android.

DNS problems

Symptom	Cause and fix
A request fails with DNS lookup for host failed: …	The host name doesn’t resolve. Check for typos and your network, or point the name at an address with DNS Spoofing. Cloak Proxy checks DNS first so these fail at once instead of hanging.
A host resolves to the wrong server	Check Tools › DNS Spoofing for a rule you forgot, and /etc/hosts.
A captured domain behaves oddly	Domains captured for apps that ignore the proxy resolve to Cloak Proxy for every app. Cloak Proxy looks up their real addresses from your network’s DNS servers, falling back to 1.1.1.1 and 8.8.8.8. Click Stop Capturing in the capture sheet to remove them.
“Couldn’t update /etc/resolver”	Capturing needs your Mac password. Try again and enter it, or cancel to leave things as they were.

Bad Gateway and other failed requests

When Cloak Proxy can’t complete a request, the app receives 502 Bad Gateway with a plain-text body explaining why and an X-Cloak-Proxy-Error: 1 header. The request appears as Failed in the list, and the inspector shows the reason above the request tabs and under No response. For an HTTPS tunnel that couldn’t connect, the inspector says Couldn’t open a connection to the host instead.

123

A failed request shows the reason in the inspector.

1. Failed, with how long it took
2. Why it failed
3. No response came back from the server

×

Message	Meaning
DNS lookup for api.example.com failed: …	The host can’t be resolved. See DNS problems.
Could not connect to api.example.com:443: …	The server refused the connection or is unreachable. Check the host, port, VPN and firewall.
Timed out connecting to api.example.com	No answer while connecting.
Timed out waiting for a response from api.example.com	Connected, but the server didn’t answer in time.
The request to api.example.com took longer than 5 minutes	The whole request hit Cloak Proxy’s 5-minute limit.
Aborted at the request breakpoint (or response)	You clicked Abort in the Breakpoint window.

A server with a self-signed or otherwise invalid certificate (common on development and staging servers) fails certificate checks. To skip the check for specific hosts, add them to insecureUpstreamHosts with update_settings through the control API or MCP. Those requests are tagged Insecure TLS. Only do this for servers you control.

If requests fail only when an external proxy is set, check its host, port and credentials in Settings › Network.

cloakctl and MCP errors

Message	Fix
Couldn't reach Cloak Proxy on port 9090. Is the app (or cloakctl run) running?	Open the app, or pass --port N if it listens elsewhere.
Missing or wrong X-Cloak-Token	The request didn’t send the token from ~/Library/Application Support/CloakProxy/api-token. See Control API.
The API is only available on this Mac	The API refuses other machines by design.
… needs the Cloak Proxy app; cloakctl run only serves the read API	Open the app for anything beyond reading and replaying traffic.
No collection named …	Run cloakctl collection list, or pass --workspace DIR.

Related

How it worksProxies, tunnels, TLS interception and the proxy guard explained.

SettingsEvery option and its default.

Failed requests and tunnelsRead what the inspector says about failures.

FAQShort answers to common questions.