Troubleshooting
New in 1.1
Run Diagnose Setup
On this page
Diagnose Setup checks capture in order of cause and names the first thing that stops it. Run it when capture looks on but no traffic arrives.
Run it
- Choose Capture ▸ Diagnose Setup….
- Read the alert's title. It says whether capture works.
- Act on the first entry in the alert. Later entries are often symptoms of the first one.
- Run it again after each change.
The alert has one of these titles:
| Title | Meaning |
|---|---|
| "Capture is running" | Capture is on and no check found a problem. Warnings can still be listed. |
| "Capture is not working yet" | A check found a problem that stops capture. |
| "Capture is not running" | No check found a problem, but capture is starting or stopping, or macOS reports it as reasserting. The Capture entry says which, such as "Capture is reasserting; ask again in a moment." Run it again in a moment. |
Below the title, the alert lists each check that is not OK. Each entry names the check, says what it found and, when there is a fix, says what to do. If every check passed, the alert says "Every check passed."
The alert offers a button for the first problem, with Cancel beside it:
- Open System Settings when the first problem is Network extension.
- Show in Finder when the first problem is App location. It selects ReqRes.app, so you can move it.
- Restart Capture when the first problem is Delivery to ReqRes, unless another copy of ReqRes holds the capture.
Otherwise, the alert has only OK.
Diagnose Setup is in 3 more places:
- The toolbar shows an orange warning button beside the capture button while setup is not finished. Clicking it runs Diagnose Setup.
- The ReqRes menu bar menu shows Diagnose Setup… while its first line reads "Setup needs attention".
- The Destinations window shows a Diagnose Setup… button while capture is not set up.
The checks, in order
Only the first 5 checks can report a problem that stops capture. The rest can only warn, and 3 of them are always OK, so they never appear in the alert. Some checks are listed only when they have something to say. If ReqRes cannot make a check, the alert lists it with the reason.
| Check | What it checks | If it is not OK |
|---|---|---|
| App location | That ReqRes runs from /Applications. It matters only until the network extension is running. | "Move ReqRes.app to /Applications and reopen it." See Install ReqRes. |
| Network extension | That the extension is installed, switched on and has its VPN configuration. | Depends on the state. See Network extension states. |
| Capture | That capture is on. | "Start capturing — ⌘⇧C, or Capture ▸ Start Capturing." |
| Proxy port | That the proxy accepts connections on 127.0.0.1 at the port set in Settings ▸ Capture ▸ Proxy port, 8034 by default. Runs only while capture is on. | Stop capture, quit anything else using that port, and start capture again. A port that another program already holds usually stops capture from starting, with an alert. See The proxy port is busy. |
| Delivery to ReqRes | That what capture records reaches this copy of ReqRes. While capture is off, it says there is nothing to deliver yet. | Click Restart Capture in the alert, in the traffic list or in the menu bar menu. It stops capture and starts it again, so the extension connects to this copy of ReqRes. If another copy of ReqRes holds the capture, use that copy, or quit it and start capture here. See ReqRes quit while capturing. |
| ReqRes CA | That the ReqRes CA certificate is in your keychain. | "Open ReqRes ▸ Settings ▸ Certificate and click Install CA certificate, then Trust." Until then, each HTTPS connection is relayed as one row, with no requests, URLs, headers or bodies. |
| CA trust | That macOS trusts the installed certificate. | "Open ReqRes ▸ Settings ▸ Certificate and click Trust." Until then, HTTPS is relayed the same way. See HTTPS rows say "not decrypted". |
| Older ReqRes CA | That no older ReqRes CA certificate is still in your keychain. Listed only when one is. | "Open ReqRes ▸ Settings ▸ Certificate and click Replace Old Certificate." See An older ReqRes certificate is still installed. |
| Exported CA file | That the CA file you exported for command-line tools holds the certificate ReqRes uses now. Listed only when it does not. | Export it again with Export CA Certificate… in Settings ▸ Capture, then copy the environment lines again. Until then, node, curl and other tools pointed at the file fail on HTTPS. See node rejects HTTPS responses. |
| Free-tier inspections | In the free version, how many of the 10 HTTPS inspections are left in this launch. | When they are used up, only the detail pane in the ReqRes window stops. Capture, the traffic list and agent reads go on. Quit and reopen ReqRes for another 10, or upgrade to Pro. See Free version and Pro. |
| Captured traffic | That at least 1 request has arrived. Runs only while capture is on. | Make a request from the app or browser you are debugging. See Fix missing traffic. |
| Apps refusing ReqRes's certificate | Which apps refused ReqRes's certificate in this run, by host and app. Runs once something is captured. | Type outcome:failed in the search field to see the rows. ReqRes remembers an app that pins its certificate, so a retry in that app works. A command-line tool usually needs the CA as a file. See An app pins its certificates. |
| What this version captures | What ReqRes captures, protocol by protocol, and what it relays or never sees. | Always OK. See Supported protocols. |
| Process attribution | That ReqRes can tell which app opened each connection. Runs only while capture is on. | The App column is hidden, and capture is unaffected. See The App column is missing. |
| Destinations | That captured requests can be placed in a country. Runs only while capture is on, once 20 requests are captured. | "Reinstall ReqRes." when the country table cannot be loaded. "Stop and start capture; if that does not change it, restart the Mac so macOS swaps in the new extension." when requests carry no server address. |
| HTTP/2 capture | Whether Capture HTTP/2 (beta) is on in Settings ▸ Capture. | Always OK. See Capture HTTP/2 and gRPC. |
| Which clients are captured | Which kinds of client read the system proxy. | Always OK. See Capture command-line tools and agents. |
Delivery to ReqRes can also warn for a few seconds, with the alert's title still "Capture is running":
- After ReqRes opens while capture is already running, for example after a crash, it says "Capture kept running while ReqRes wasn't receiving it, and its extension is reconnecting to ReqRes — what it captured meanwhile arrives when it does; ask again in a moment."
- Right after capture starts, it says "The extension has not connected to ReqRes yet; ask again in a moment."
Run Diagnose Setup again a moment later. Both warnings go once the extension connects.
Network extension states
The Network extension check reports one of 4 states:
| The check says | What to do |
|---|---|
| "The network extension is not installed, so nothing can be captured." | Click the capture button in ReqRes, then approve the extension in System Settings ▸ General ▸ Login Items & Extensions. |
| "The extension is installed but switched off." | In System Settings ▸ General ▸ Login Items & Extensions, click the ⓘ button next to Network Extensions, then switch ReqRes on. |
| "macOS has no VPN configuration for ReqRes yet." | Start capture, then choose Allow when macOS asks to add a VPN configuration. No real VPN is involved. |
| "The extension was updated and needs ReqRes restarted." | Restart your Mac. macOS finishes installing the updated extension when the Mac restarts, and Restart Now in the "Restart Recommended" alert does it for you. Quitting and reopening ReqRes only clears the message. |
The check always names the macOS 15 path. On macOS 14, see Set up capture.
Agents run the same checks
An AI agent connected over MCP runs the same checks with the diagnose_setup tool. The report differs from the alert in 4 ways:
- It starts with a verdict. When a check stops capture, the verdict is that check's finding and its fix. Apps refusing ReqRes's certificate and Exported CA file never become the verdict.
- It lists all checks, including the ones that passed. Each line starts with
ok,FAIL,warnor?. - Its fix text is addressed to the agent, as in "Ask the user to…". Only you can approve the extension or trust the certificate.
- What this version captures carries the whole protocol table, cut to names and statuses while a check stops capture. Which clients are captured names the tools that ignore the system proxy, such as curl, git, the Claude Code CLI and node, and tells the agent to call
capture_environment.
After ReqRes reconnects to a capture that kept running without it, the agent's Delivery to ReqRes line says for 5 minutes how many requests the extension delivered, and how many earlier ones, if any, were not kept.
To ask for a report, use a prompt such as:
Call diagnose_setup and tell me the first thing I need to fix.See MCP tools for the other tools.