Troubleshooting

A short list of issues that come up most often. If yours isn't here, email info@useprobe.app 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.

1. Open Certificate → Setup Guide from the menu bar.
2. Pick the platform you're trying to debug (macOS, iOS, Android).
3. 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.

Every HTTPS site shows a security warning in my browser

Symptom: right after installing Probe, opening any browser on the same machine produces "Your connection is not private" / "NET::ERR_CERT_AUTHORITY_INVALID" on every HTTPS site. Sometimes Probe doesn't surface its in-app warning banner either.

Cause: the MITM Root CA (probe_ca, generated locally on first launch) is not currently trusted by the OS. Every HTTPS leaf certificate Probe mints is signed by that CA, so the browser rejects them. Happens on macOS and Windows alike — typically when:

• You skipped or dismissed the first-launch welcome dialog without installing the CA.
• You upgraded from an older build: Probe replaced its old CA with a new Probe Root CA, which isn't installed yet.
• Probe made a new CA (for example after you deleted probe_ca), or another Probe install's CA is trusted on this machine. Probe only counts the CA it is using, matched by its fingerprint, so the banner says Probe has a new certificate: install that one too.
• (Windows, upgraded users only) You originally installed via the retired ProbeBootstrap.exe, which dropped a code-signing root CA into the trust store but never the MITM CA. The MITM CA is a separate certificate and still needs to be installed. See the note below.

Fix (re-install the MITM CA):

macOS

1. Open Probe.
2. Start the proxy (the install button stays disabled and reads Start proxy first until it runs).
3. Menu bar → Certificate → macOS Setup Guide, then click Install & Trust Certificate and approve the Keychain prompt with your password / Touch ID.
4. Fully quit and reopen your browser — most browsers snapshot the trusted-root list at startup, so an existing tab won't pick up the new CA.

Windows

1. Open Probe.
2. Menu bar → Certificate → Install CA Certificate… (runs certutil -addstore -user Root against %LOCALAPPDATA%\Probe\probe_ca\ca_cert.der).
3. Approve the trust prompt.
4. Fully quit and reopen your browser.

Caution

Don't be fooled if Probe Internal Root CA is already in your trusted roots — that's the legacy code-signing CA that the retired ProbeBootstrap.exe dropped into the trust store on older installs, not the MITM CA. (Current builds use an externally trusted EV cert and don't install any root.) The MITM CA always has a parenthesised suffix like Probe Root CA (2026-05-11, my-machine, abc12345).

Verify: visit any HTTPS site through Probe — the lock icon should show Probe Root CA (date, host, id) as the issuer when you click it and inspect the certificate chain.

See Install CA on macOS or Install CA on Windows for the manual procedures if the in-app installer doesn't run for any reason.

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.

1. Open Settings → General → VPN & Device Management → Probe Root CA, tap Install.
2. Then go to Settings → General → About → Certificate Trust Settings.
3. Toggle the switch next to Probe Root 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:

1. 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.
2. 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 is still on after Probe quits

Probe switches off the system proxy it turned on when it quits. A proxy you configured yourself, or any proxy while Auto-enable system proxy is off, is left as it was. 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 five 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 Ignore host button on the banner.

The update doesn't download or install

Probe updates itself with Sparkle on macOS and WinSparkle on Windows; see the update section of the macOS or Windows install page.

• Check your internet. If the update feed or the download can't be reached, Sparkle or WinSparkle shows its own error in the update window; try Check for Updates… again later.
• On a corporate network the feed or download might be blocked; email info@useprobe.app and we'll help you get the latest installer.
• Probe never forces an update, so a failed update never stops you from using the version you have.

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

probe-mcp keeps running even when Probe isn't, so the AI client doesn't lose it. Common messages:

• Cannot read handshake file at … (on stderr at startup) or a tool answering Probe is not running (no valid …/api-handshake.json) — Probe isn't running, or it crashed and left no handshake. Start Probe; the next tool call works.
• Probe app (PID nnnn) is no longer running. (on stderr) — the handshake file is stale; the app exited without removing it. Start Probe again; it'll overwrite the file.
• … cannot reach Probe (…). Is the Probe app running? — the API isn't answering on the port in the handshake. Open Probe (the API runs whenever the app is open, proxy started or not).

You don't need to restart your AI client after starting or restarting Probe: probe-mcp re-reads the handshake when a call can't connect or gets 401, and retries once. If you run Probe with a custom PROBE_DATA_DIR, give probe-mcp the same variable.

See MCP Setup.

Composer says "request didn't go through proxy"

Composer requests normally 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 Upstream Proxy is enabled with Composer requests ticked, Composer sends straight to the upstream proxy and skips Probe, so those requests don't appear in the log. Untick Composer requests under Tools → Upstream Proxy… (or turn the upstream off) and send again.
• If that upstream proxy is offline, the request fails before it lands.

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:

1. Master switch — Tools → Map Local…, top right. If off, no rule matches.
2. Rule enabled — the per-row checkbox.
3. 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/*.
4. Method — if match_all_methods is off and your method is GET, only GET requests match.
5. 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.

A domain I visited isn't showing up in the log

First check whether the domain is ignored. An ignored host is forwarded straight through without decryption, so it produces no log entries at all — the traffic happens, Probe just never records it.

1. Open the sidebar's IGNORED section (under the domain tree). It lists every host currently ignored.
2. If your domain is there, right-click it and choose Un-ignore (or use the remove control). Capturing resumes immediately — no restart needed.

A host can end up ignored a few ways: you right-clicked it and chose Ignore, it's one of Probe's built-in defaults (telemetry / OS keepalives), or — in older builds — the pinning detector auto-ignored it on a false positive. That auto-ignore is fixed (detection now only suggests), and the first launch after updating clears every host you'd added to the Ignored list so any lingering bad entries are gone (built-in defaults are kept). See Pinning Detection → If a host stopped being captured.

If the domain is not ignored, check that it isn't hidden by Domain Watch (an unwatched domain shows only a teaser row) or filtered out by an active Filtered List or the search box.

A device cert that used to work now says "unsecure network" / must be reinstalled

Symptom: your phone (or Windows machine) trusted Probe's CA and was decrypting fine, then after a Probe update it started showing "unsecure network", certificate warnings, or refusing HTTPS — and reinstalling the CA once fixes it.

Cause: an older build could regenerate or reserve the local Root CA in a way that left the certificate the device had trusted no longer matching the one Probe now signs leaf certs with. The device is still pinning the old CA; the new leaf certs don't chain to it, so trust fails.

This is fixed going forward — Probe now always serves the exact CA it signs with, and (on Windows) stores the CA under %LOCALAPPDATA%\Probe\probe_ca so it survives %TEMP% cleanup instead of being regenerated. But existing devices need to pick up the current CA once:

1. Remove the older Probe certificate profile from the device, including one installed under Probe's earlier name.
   • iOS: Settings → General → VPN & Device Management → tap the older Probe profile → Remove Profile.
   • Windows: certmgr.msc → Trusted Root Certification Authorities → delete the older Probe certificate.
2. Reinstall from Probe's current Certificate → Setup Guide (re-download from http://<host-ip>:9098/, don't reuse a saved file).
3. Re-enable trust (iOS: Settings → General → About → Certificate Trust Settings), then fully quit and reopen the browser/app.

After this one reinstall it stays stable across updates — except once more on the first launch after updating from a build that still used a pre-rename CA, which Probe replaces automatically (see Upgrading from an older build). See Certificate Setup.

Probe is running but my own computer's traffic isn't captured

If devices you point at Probe are captured but the host machine's own browser/app traffic never appears, check the Auto-enable system proxy setting.

Probe can run in an engine-only mode where it does not touch the OS system-proxy settings — useful when you only debug external devices, or use an upstream proxy, and don't want Probe rerouting your Mac/PC's own traffic. With it off, only clients you point at Probe explicitly (Composer, the WebSocket client, a phone configured by hand) flow through it; the host's normal apps bypass it.

Turn it back on under Settings → General → Auto-enable system proxy, or set the system proxy manually to 127.0.0.1:<proxy port>. When it's on, Probe enables the system proxy on start and turns it off on stop and quit.

The WebSocket "Messages" tab is empty

The Messages tab only shows frames for connections Probe actually intercepted (a successful MITM handshake). If the WebSocket connection was tunnelled through without decryption, the tab has nothing to show — the same causes as encrypted HTTPS bodies:

• The client's CA trust is missing, so the wss:// upgrade rode a CONNECT tunnel — install/trust the CA (see the first entries above).
• The host is ignored or pinned, so it's forwarded without interception — check the IGNORED list.

A connection made through Probe's own WebSocket client tab is always intercepted, so its frames appear in both the client tab and the Messages tab. See WebSocket.

A Map Local / Map Remote / Mock rule I created over REST or MCP doesn't fire or didn't stick

With the Probe app open, a rule created through the REST API or an MCP tool (probe_create_map_local_rule, probe_create_mock_rule, etc.) is handed to the app, which saves it and lists it in Tools → Map Local / Map Remote / Mock — it survives a restart like a rule you added there. If it doesn't fire:

• The master switch is off. Map Local, Map Remote and Mock each have one, off by default. Turn it on in the window or with probe_set_map_local_enabled / probe_set_map_remote_enabled / probe_set_mock_enabled.
• The Mock server isn't running. Start it in the window or with probe_start_mock_server.
• The call returned 504 with applied_in_proxy: true. The proxy applied the rule but the app didn't confirm it in time, so it may not be saved. Check the window and save the rule there if it's missing.
• The proxy ran without the app UI (a headless run). Rules then live only in the proxy's memory until it stops.

See also

• Certificate Setup
• Mobile Debugging
• Pinning Detection
• MCP Setup
• Settings