Troubleshooting

A short list of issues that come up most often. If yours isn’t here, open an issue on GitHub with the OS, Probe version, and a copy of ~/.probe/api-handshake.json (redact the token).

I see HTTPS traffic in the log, but the bodies are encrypted blobs

Probe’s CA isn’t trusted on the device making the requests, so it falls back to a CONNECT tunnel — Probe sees the bytes but can’t decrypt them.

Open Certificate → Setup Guide from the menu bar.
Pick the platform you’re trying to debug (macOS, iOS, Android).
Follow it end-to-end. Most missed steps are on iOS — see the next entry.

Verify by visiting http://<host-ip>:9098/ from the device after install — Probe’s CA-cert landing page should load over HTTP, and any HTTPS site you hit through the proxy should show Probe’s CA as the issuer when you inspect the certificate. The host IP is shown next to the proxy LED in Probe’s toolbar; the cert-server port is proxy port - 1 (so 9098 for the default proxy port 9099).

See Certificate Setup.

iOS isn’t showing my CA after install

You installed the profile, but didn’t enable trust for it. iOS treats those as two steps.

Open Settings → General → VPN & Device Management → Probe CA, tap Install.
Then go to Settings → General → About → Certificate Trust Settings.
Toggle the switch next to Probe CA to ON. Confirm the warning.

Without step 3, the cert is installed but not trusted, so HTTPS interception still fails.

Android app traffic is empty even with the CA installed

Android user-store CAs (the only kind a non-rooted device lets you install) are not trusted by apps by default. The system browser sees them; apps don’t.

You have two options:

Add a Network Security Config to the app that opts into user-store CAs (debug-only). Re-build the app and reinstall. This is the standard mitm workflow for Android.
Root the device and install Probe’s CA into the system store.

See Install CA on Android for the Network Security Config XML snippet.

My phone shows “no internet” after I set the proxy

Three likely causes:

Probe isn’t running. Start it. The system proxy on your phone is pointing at a port that nothing is listening on.
The phone is on a different network. It must be on the same Wi-Fi as the host machine running Probe.
A firewall is blocking the host port. Open 0.0.0.0:9099 (the proxy port) on the host machine. macOS asks the first time you run Probe — if you clicked “Deny”, reset it under System Settings → Network → Firewall.

If the proxy LED in the toolbar is green and your laptop can reach http://127.0.0.1:9099, but the phone can’t, it’s almost always the firewall.

The system proxy isn’t restored after Probe quits

Probe disables the system proxy on graceful quit. If Probe crashed or was force-killed, the system proxy can be left pointing at a dead port.

macOS:

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

(Replace Wi-Fi with your active network service name from networksetup -listallnetworkservices.)

Windows: open Settings → Network & Internet → Proxy, turn off Use a proxy server.

Some apps refuse to connect even with the CA installed

The app implements certificate pinning — it ships its own list of trusted CAs and rejects every other one, including Probe’s. There’s no proxy-side fix; the app code has to change, or the binary has to be patched.

This is by design: pinning protects users from exactly the kind of inspection Probe does. For your own apps, drop pinning in debug builds. For third-party apps, you can’t.

Probe spots this pattern automatically — when three or more handshakes to the same host fail in a 30-second window with no inner traffic flowing, a banner appears at the bottom of the main window naming the host. See Pinning Detection for the detection rules and the Add to Ignored workaround.

The auto-update download fails

Probe pulls updates from S3 (guide-mitm-proxy-app, ap-northeast-1).

Check your internet — the in-app updater times out silently if the bucket is unreachable.
If you’re on a corporate network, the bucket might be blocked; download the latest DMG/MSIX manually from the GitHub releases page.
An update marked min_version is non-dismissible. If you can’t dismiss the dialog, that’s intentional — update to continue using Probe.

probe-mcp can’t connect

The MCP server prints to stderr when something’s wrong. Run it directly to see the message:

/Applications/Probe.app/Contents/MacOS/probe-mcp

Common causes:

Cannot read handshake file at … — Probe isn’t running, or it crashed and left no handshake. Start Probe.
Probe app (PID nnnn) is no longer running. — handshake file is stale; the app exited without removing it. Start Probe again; it’ll overwrite the file.
Cannot reach Probe API: … — the recorded port is no longer reachable. Restart Probe.

After fixing, restart your AI client so it re-spawns probe-mcp and re-reads the handshake.

See MCP Setup.

Composer says “request didn’t go through proxy”

Composer requests do flow through Probe’s proxy, so they appear in the log. If they don’t:

Check that the proxy is running (toolbar Start/Stop button).
If you set an upstream proxy and it’s offline, the request fails before it lands. Disable upstream proxy under Settings → Upstream.

Probe shows blank traffic after I imported a session

The session was loaded, but you’re looking at the recording tab, which is empty by default. Switch to the imported tab — its name is whatever the imported file’s name field said. The tabs sit at the top of the log table area.

Map Local rule doesn’t fire

Five things to check:

Master switch — Tools → Map Local…, top right. If off, no rule matches.
Rule enabled — the per-row checkbox.
URL pattern — Probe sees MITM-intercepted URLs with the explicit :443/:80 port. Rule patterns should not include the port (Probe normalizes both sides). Use api.example.com/users/*, not api.example.com:443/users/*.
Method — if match_all_methods is off and your method is GET, only GET requests match.
Run the match preview — Tools → Map Local → Check Match (or via MCP probe_check_map_local_match). It tells you exactly which rule (if any) would fire.

The same rules apply to Map Remote.