Troubleshooting

I only see CONNECT rows, with no status and no body#

The host is not being decrypted. The SSL Proxying Include list starts empty, and an empty list decrypts nothing. Right-click the row and choose Enable SSL Proxying for This Host, then repeat the request. See SSL Proxying.

If the host is on the list and it still shows as a tunnel, the device may not trust your WireLens root. Check Settings ▸ Certificate on the Mac, or the setup screen on iPhone.

The browser says "Your connection is not private"#

The WireLens root is not trusted where that browser looks:

• Chrome, Safari, Edge, Arc: trust the root in the macOS keychain. A root in your login keychain without trust settings can look installed and still fail in Chrome; use Certificate ▸ Install for All Users…, or set Always Trust in Keychain Access.
• Firefox: Certificate ▸ Install into Firefox.
• iPhone: turn on full trust in Settings ▸ General ▸ About ▸ Certificate Trust Settings.

Chrome can remember a certificate error for a host for a while. After fixing trust, restart the browser.

An app stops loading after I decrypt it#

It pins its certificate and refuses any certificate but its own. WireLens notices a host that refuses its certificate twice and passes it through for the rest of the session, so it recovers on its own. To stop decrypting it for good, remove it from the Include list or add it to Exclude. See Certificate pinning.

Nothing from my app shows up at all#

• Capture is not running. Press ⌘R on the Mac, or start it from the Traffic tab on iPhone.
• The scope is Manual clients & devices. In that scope macOS proxy settings are untouched. Switch to This Mac — HTTP & HTTPS in Settings ▸ Capture.
• The app ignores the system proxy. Command line tools, runtimes, containers and some frameworks do. See Client setup.
• The app uses HTTP/3. Turn on Block QUIC so it falls back to TCP. See HTTP/2 and HTTP/3.
• The Allow List has entries and this host is not one of them. See Allow List and Block List.

My local dev server does not appear#

macOS sends localhost and private addresses around the system proxy, so apps using the system proxy reach a local server directly. Point the client at WireLens explicitly and it is captured and can be decrypted:

curl -x http://127.0.0.1:9090 http://localhost:3000/

My Mac has no internet after WireLens quit unexpectedly#

The system proxy may still point at a WireLens that is no longer running. Open WireLens and choose Capture ▸ Restore System Proxy, or run wirelens proxy restore. Stopping capture and quitting normally always restores your settings.

Port 9090 is already in use#

Another tool is listening there. Settings ▸ Capture offers the next free port. Update any clients you pointed at 9090 by hand.

A rule does nothing#

• The host is not decrypted. Map Local, Map Remote, Rewrite, Breakpoints and Scripting can only act on HTTPS they can read; the Tools pane says when a rule targets a host that is not on the Include list.
• The tool's master switch is off. Breakpoints and Scripting have one.
• The rule is past the free plan's limit, so it is switched off. The rule pane shows this, and Pro turns it back on.
• The pattern does not match. Test it against the flow's full URL, including the scheme.

A breakpoint left my app hanging#

That is what a breakpoint does: it holds the request until you act. Open Waiting Traffic (⇧⌘B) and execute or abort it. Every rule has a timeout, so a forgotten pause always ends.

A DNS Spoof rule makes the host hang on iPhone#

The target is an address the device cannot connect to, such as 127.0.0.1 or a link-local address. The editor warns about these. Point the rule at an address on your network.

Bodies are cut short#

Very large bodies are kept truncated and marked that way. On the Mac, raise Body capture limit in Settings ▸ Capture. On iPhone the limit protects the phone's network under iOS's memory limit for network extensions.

Pro features stopped working#

• The trial ended. Settings ▸ License says so and lists what went back to free limits.
• The Mac has not reached the license service for more than seven days. Connect once and Pro returns.
• The key was released on this Mac, or moved to another one.

See Licenses, trial and activation.

The command line or an agent says WireLens is not running#

Capture, proxy and certificate commands are requests to the app, which owns the proxy. Open WireLens and try again. Read commands such as wirelens ls work with the app closed.

Still stuck#

Write to support@wirelens.app with your Mac or iPhone model, OS version, WireLens version, and what you expected to happen. On the Mac, Settings ▸ Diagnostics can export a debug log to attach. Never send us your license key in full.