Troubleshooting
Open Help ▸ Setup & Health… first. It shows the state of each part, with a fix button for each problem.
Nothing appears in the table
Section titled “Nothing appears in the table”Work down this list.
- Is capture on? Check the menu bar icon and the capture button in the main window.
- Is the app chosen? Open Settings ▸ Capture and check the app is listed, or switch to “all apps except”.
- Restart the app you are watching. Puffin only claims connections opened after capture starts.
- Is the proxy configuration enabled? A proxy configuration that reads “Not configured” means no capture at all. Enable it in Setup & Health.
- Is the extension active? See below.
- Is it a browser? Browsers use helper processes. Puffin matches these automatically, so choose the browser app itself.
The extension will not activate
Section titled “The extension will not activate”- The app must be in
/Applications. - Approve it in System Settings ▸ General ▸ Login Items & Extensions ▸ Network Extensions.
- macOS may ask for a restart.
- Allow the “Add proxy configuration” prompt.
- After a restart, or after the extension is replaced by a newer build, a saved proxy configuration does not always start by itself. Puffin starts it again when the extension becomes active. If it does not, use the fix button in Setup & Health.
I can see requests, but HTTPS bodies are empty
Section titled “I can see requests, but HTTPS bodies are empty”By default Puffin does not decrypt anything. Add the host to the SSL proxying list, from the context menu or Settings ▸ TLS, then make the request again. Decryption applies to connections opened afterwards.
An app says the certificate is not trusted
Section titled “An app says the certificate is not trusted”- Make sure the certificate is installed and trusted in Settings ▸ TLS.
- The tool may ignore the Keychain. See Environment variables.
- For the iOS Simulator, install the certificate into the simulator. See iOS Simulator.
A host says “TLS rejected — likely pinned or CA not trusted”
Section titled “A host says “TLS rejected — likely pinned or CA not trusted””The app closed the connection after seeing Puffin’s certificate. Either the certificate is not trusted by that app, or the app pins certificates. If it is pinned, use the bypass button so the app works normally. Puffin does not defeat pinning.
A request shows an error
Section titled “A request shows an error”The inspector says what failed: connect, TLS, a client abort or a timeout. For a server certificate problem you can allow an invalid certificate for that host in Settings ▸ TLS.
Bodies look garbled
Section titled “Bodies look garbled”Bodies are stored as sent and decoded only for display. gzip, deflate, Brotli and zstd are understood. A body in another encoding shows as sent. Try the Raw or hex viewer.
Keeping the capture small
Section titled “Keeping the capture small”Lower the stored-request and body-size limits in Settings ▸ Storage (they apply at the next launch), or use Clear in the main window.
Still stuck
Section titled “Still stuck”Quit Puffin and check that the network works normally. This is by design: with the app closed, the extension lets traffic go direct, so you can tell whether a problem comes from Puffin.