Fix HTTPS and certificate errors

Each section starts with what you see.

HTTPS rows say "not decrypted"#

Each HTTPS connection is one row, written when it closes. The row shows the host and port, "not decrypted", and the bytes sent each way. There are no requests, URLs, headers or bodies. Apps keep working, because ReqRes passes the connection on with the server's own certificate and refuses nothing.

The ReqRes certificate is not installed, or not trusted. Diagnose Setup reports ReqRes CA or CA trust.

1. Open Settings ▸ Certificate. The menu item Certificate ▸ Install CA Certificate... opens the same tab.
2. Under ReqRes CA, read the Keychain row. If it says Not installed, click Install CA certificate.
3. In the Trust row, click Trust. macOS asks for your password.
4. Check that the Trust row says Trusted.

New HTTPS connections are decrypted at once, and you do not need to restart capture. A connection that was already open stays relayed until the app that opened it reconnects. To see its requests now, quit and reopen that app.

If you cancel the macOS prompt, the row stays Not trusted. Click Trust again. If macOS refuses the change, ReqRes shows "The ReqRes certificate could not be changed" and the reason.

HTTP requests never need the certificate. See Trust the ReqRes certificate.

An older ReqRes certificate is still installed#

At launch, ReqRes shows a sheet titled "Replace the Old ReqRes Certificate". Settings ▸ Certificate shows an orange banner with a Replace Old Certificate button, and Diagnose Setup reports Older ReqRes CA.

ReqRes creates its certificate the first time it runs. A certificate named "ReqRes CA" left by an earlier version or an earlier installation is no longer used, and it should not stay trusted.

1. Click Replace Old Certificate, in the sheet or in the banner.
2. Enter your password when macOS asks. An old certificate trusted for all users of the Mac needs an administrator's password.

ReqRes removes the old certificate's trust and then the certificate, installs and trusts the current one, and restarts capture if it is running. Not Now removes nothing, and the banner stays in Settings ▸ Certificate until the old certificate is gone.

To list the certificates named "ReqRes CA" in your login keychain, with their SHA-1 fingerprints, run:

security find-certificate -a -Z -c "ReqRes CA" ~/Library/Keychains/login.keychain-db | grep SHA-1

To remove the old certificate by hand, delete the "ReqRes CA" whose SHA-1 is not this Mac's. The ? button at the bottom of Settings ▸ Certificate opens the About the ReqRes Certificate sheet, which shows this Mac's SHA-1 under "Its details" and the Keychain Access steps. Its Terminal command removes this Mac's certificate, not the old one.

codesign fails while capturing#

codesign fails with "A timestamp was expected but was not found", for code that has nothing to do with ReqRes.

Code signing asks Apple's timestamp service for a signed timestamp, and can fail while that request goes through ReqRes. ReqRes excludes timestamp.apple.com from interception by default to prevent this.

1. Open Settings ▸ Capture and find Excluded from interception.
2. Check that timestamp.apple.com is in the list.
3. If the list is empty, click Restore the recommended hosts. If some recommended hosts are missing, click Add the recommended hosts.
4. Sign again.

If signing still fails, stop capture while you sign.

An app pins its certificates#

An app's request fails the first time it meets ReqRes, and works when you try again. The traffic list shows one Failed row for that host, then rows marked with the app's name, such as "SSL pinned by WhatsApp".

An app that pins its certificates accepts only the certificate it expects from its server. It refuses ReqRes's, even when you trust the ReqRes CA. After the first refusal, ReqRes remembers the app and the domain, and passes that app's later connections there through untouched. Each connection is still a row with the host and port, the bytes each way and how long it was open. Nothing inside it can be read.

A refusal alert from the app counts at once. A connection the app closes without an alert counts only when it happens again within 30 seconds, because a browser's spare connection looks the same. If no Failed row appears, try again in the app within 30 seconds.

Settings ▸ Capture ▸ SSL-pinned apps lists what ReqRes remembered. Click Forget to try decrypting that app's domain again, or Forget All.

iCloud, Software Update, the App Store, push notifications, Find My and the other hosts on macOS's own pinning list accept only Apple's certificate. ReqRes relays them automatically, as rows such as "SSL pinned by macOS · iCloud". There is nothing to do.

To pass a host through with no row at all, add it under Settings ▸ Capture ▸ Excluded from interception, then quit the app and open it again. HTTPS connections opened after the change pass through.

A Failed row can also offer Exclude api.example.com…, which asks "Stop recording api.example.com?" first. ReqRes does not decrypt, record, change or hold an excluded host. See Keep SSL-pinned apps working and Pass a host through untouched.

A server's certificate or TLS fails#

A request fails with a Failed row, and the app gets 502 Bad Gateway from ReqRes. The response's body is the reason, the same sentence the row shows. A native gRPC client gets no answer instead: ReqRes can only offer it HTTP/1.1, so the client closes the connection, and the row says "ReqRes could not reach the server to agree on HTTP/2".

With the certificate trusted, ReqRes opens all TLS through the proxy as HTTPS. So a protocol other than HTTP inside TLS, such as IMAP or SMTP over TLS or a database over TLS, fails. Exclude its host.

An HTTP/2-only app or a gRPC client fails#

While Capture HTTP/2 (beta) is off, ReqRes speaks HTTP/1.1 to apps. An app that speaks only HTTP/2 closes the connection, and its Failed row ends: "Capture HTTP/2 is off — turn it on in Settings ▸ Capture. This is not certificate pinning; excluding the host is not the fix."

A native gRPC client fails the same way. Turn on Capture HTTP/2 (beta) in Settings ▸ Capture. It applies to connections opened after the change. See Capture HTTP/2 and gRPC.

node rejects HTTPS responses#

node, or a tool built on it such as the Claude Code CLI, fails its HTTPS requests while its traffic goes through ReqRes. In ReqRes, its requests are Failed rows, and the row offers Export the CA and the environment lines…, which opens Settings ▸ Capture.

node does not read the keychain. Trusting the ReqRes CA in Settings ▸ Certificate is enough for Safari, but node needs the certificate as a file, named in NODE_EXTRA_CA_CERTS. Without it, node rejects the certificate ReqRes presents.

1. Open Settings ▸ Capture.
2. Under Capture a command-line tool, click Export CA Certificate…. The save panel proposes reqres-ca.pem in your home folder.
3. Click Copy above the Environment block, and paste the lines into the terminal.
4. Restart the tool from that terminal.

The line node reads points at the file you exported, for example:

export NODE_EXTRA_CA_CERTS=/Users/you/reqres-ca.pem

Before you export, the line names ~/reqres-ca.pem, and the block adds a security command that writes the certificate from your login keychain to that file. The command picks the certificate by its SHA-256 fingerprint, because an older certificate named "ReqRes CA" can sit beside it.

A file exported by an earlier version or installation holds an older certificate, and tools pointed at it fail on HTTPS. Settings ▸ Capture then shows "~/reqres-ca.pem holds an older CA — export again", and Diagnose Setup reports Exported CA file. Click Export CA Certificate… again, then copy the lines again.

After a tool refuses the certificate, ReqRes can remember it like a pinning app and relay its later connections, marked "SSL pinned by node". Once the tool has the certificate, click Forget next to it in Settings ▸ Capture ▸ SSL-pinned apps.

Other tools read other variables, and the copied lines set them all. See Capture command-line tools and agents.

SSL_CERT_FILE breaks requests to excluded hosts#

With the environment lines set, a tool cannot verify one host's certificate. That host is in Excluded from interception, such as timestamp.apple.com, or its rows are marked "SSL pinned".

SSL_CERT_FILE replaces the tool's trust store with the ReqRes certificate alone. ReqRes passes such a host through untouched, so the tool sees the real server's certificate and cannot verify it.

Do one of these:

• Run that one command without the variable:

  TerminalCopyCopied code

  env -u SSL_CERT_FILE curl https://api.example.com/

• Remove the host from Excluded from interception while you need it.

The Destinations map goes blank while capturing#

The map tiles come from Apple Maps servers under *.ls.apple.com. ReqRes excludes them from interception by default, so the tiles pass through untouched.

1. Open Settings ▸ Capture.
2. Check that *.ls.apple.com is in Excluded from interception.
3. If it is missing, click Add the recommended hosts. If the list is empty, click Restore the recommended hosts.
4. Stop capture and start it again. An exclusion applies only to connections opened after it.

Map servers on macOS's own pinning list are relayed even when they are not excluded, as rows marked "SSL pinned by macOS · Maps and Location". The map also needs a network connection. Without one, the window says: "Map tiles need a network connection; destinations are still listed."

Related#

• Trust the ReqRes certificate
• Keep SSL-pinned apps working
• Pass a host through untouched
• Capture command-line tools and agents