Troubleshoot a capture
Work from the first missing observation instead of changing every setting at once.
Start with the first observation you cannot make. A listener starting, a request arriving, a body being readable, and the app recovering are four different results.
No requests from the target
Check: Is the listener running on the Mac at the address and port the target uses? Did the app make a fresh request? Remove old filters and trigger one recognizable action. A request from a browser or another device proves only that client’s route.
Next: Follow the guide for the actual Mac app, Simulator, iPhone/iPad, or Apple TV. If the listener port is occupied, choose an available port in the app and update the target to match. Do not change certificate trust to fix a missing route.
A tunnel or byte count appears, but no readable body
Check: Determine whether HTTPS was inspected or tunneled. A tunnel does not expose the HTTP body. For inspected traffic, look for an omission, retention limit or truncation notice, especially after opening a recording.
Next: For a permitted test host, verify the test authority on the actual target and the host’s inspection scope. A pinned client may reject inspection; use its supported test configuration or keep it tunneled. If the bytes were not saved, make a fresh recording with suitable fidelity instead of changing trust.
The agent can list a tool but cannot use it
Check: Was the local server running, was this client enrolled, and did it request an operation covered by its capability and disclosure profile? A list of tools is not an authorization receipt. An operation awaiting local approval differs from one that was denied.
Next: Compare the requested operation with the exact MCP entry, then review its scope on the Mac. For a documentation question, prefer searching product help over requesting a response body. Respect a refusal; do not try other interfaces to evade it. MCP setup and cleanup.
The CLI reads help but a live query fails
Check: Offline help requires neither a live capture nor an authenticated MCP session. Run joesproxyctl doctor and check the configured endpoint and enrollment. A valid session returning no matching rows is different from a connection or authorization error.
Next: Confirm the request exists in Table, then narrow by the correct host and time. For documentation syntax or offline topic IDs, consult the CLI reference and CLI setup guide.
A rewrite was saved but nothing changed
Check: Look for the next matching request after activation. Compare the actual method, host and path with the rule. Inspect the returned field, override attribution and any subsequent request the changed value should trigger.
Next: If the request never arrived, investigate refresh and caching first. If it did, check other active rules and the exact field path. If delivery matches, observe rendering separately. Local overrides · Effect Bundles.
Throttling looks ineffective
Check: Did the app fetch the same asset on both runs over a supported inspected route? A local cache, opaque tunnel or different asset invalidates the comparison.
Next: Record a fresh baseline and change only bandwidth or latency. Use Timeline to compare transfer duration and the gaps before or after it. Network conditioning.
Segments returned 200, but audio or video did not recover
Check: Which playlist and rendition were requested after the seek or language switch? Did the player actually produce audio or an image? Segment transfer alone answers neither question.
Next: Repeat the same action against the aligned baseline, change one condition and annotate the observed playback separately. HLS investigation.
Networking stopped after the test
Check: Is the network service still pointing at a stopped listener? Are a mock, fixture redirect, throttle or temporary trust profile still present?
Next: Disable your test effects, restore the specific service’s previous proxy configuration and remove only the trust you added. Do not reset unrelated network interfaces. Verify ordinary connectivity with the listener stopped. For an interrupted capture, preserve available previous-session evidence before replacing the workspace.
