Troubleshooting

wirelens ships inside the app and is not on your PATH until you link it once.

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 leaves every host tunnelled. Add the host, then make the request again:

• Mac: right-click the row and choose Enable SSL Proxying for followed by the host name.
• iPhone and iPad: long-press the host and choose Enable SSL Proxying.
• Android: long-press the host and choose Enable SSL Proxying.

See SSL Proxying.

If the host is on the list and still shows as a tunnel:

• The device may not trust your WireLens certificate. Check Settings ▸ Certificate on the Mac, Settings ▸ Certificate (Full Trust) on iPhone, or Settings ▸ Setup Guide on Android.
• On an Intel Mac, WireLens captures HTTPS as CONNECT rows only and shows a banner that says so. Decrypting needs a Mac with Apple silicon.

The browser says "Your connection is not private"#

The WireLens certificate is not trusted where that browser looks:

• Chrome, Safari, Edge, Arc on the Mac: trust it in the macOS keychain. A certificate installed for your account 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 and iPad: turn on full trust in Settings ▸ General ▸ About ▸ Certificate Trust Settings.
• Android: install the certificate as a CA certificate, from Settings ▸ Setup Guide in WireLens.

Chrome remembers a certificate error for a while. Restart it after fixing the trust.

An app stops loading after I decrypt it#

It trusts only its own certificate. WireLens notices a host that keeps refusing its certificate and passes it through untouched for the rest of the session, and the app recovers by itself. On iPhone this is Auto-passthrough Pinned Hosts in Tools ▸ SSL Proxying, which acts after two refused handshakes; on Android it is Keep apps working. To stop decrypting it for good, remove it from the Include list or add it to Exclude. See Certificate pinning.

My app does not appear at all#

• Capture is not running. Press ⌘R on the Mac, or start it from the capture bar on iPhone or the capture button on Android.
• Mac: WireLens is not the system proxy. With Set as the macOS system proxy off in Settings ▸ Capture, WireLens listens only for clients you point at it. Turn it on.
• Mac: the app ignores the macOS proxy setting. Command line tools, runtimes, containers and some frameworks do. Point them at WireLens with Client setup, or install the experimental Network Extension in Settings ▸ Capture, which captures apps that ignore the proxy setting.
• Mac: the Capture Allow List has entries and this host is not one of them. See Allow List and Block List.
• Android: the app is not chosen in Tools ▸ Apps. A change there applies the next time capture starts.
• Decrypt HTTP/3 is on and the host is not on the SSL Proxying list. Its QUIC goes to the server untouched. Add the host to the list, or turn Decrypt HTTP/3 (Experimental) off (Settings ▸ Network on the Mac, Tools on iPhone and Android) and the app falls back to TCP. See HTTP/2 and HTTP/3.

My local dev server does not appear#

On the Mac, localhost traffic is captured, but the macOS proxy settings send localhost and private addresses around the proxy for some apps. Point the client at WireLens yourself 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#

Your Mac may still be pointing at a WireLens that is no longer running. Open WireLens and choose Capture ▸ Restore System Proxy (also in the menu bar item), or run wirelens proxy restore. Stopping capture and quitting normally always puts your settings back.

Port 9090 is already in use#

Another tool is listening there. Settings ▸ Capture offers the next free port, for example Use 9091. Update anything you pointed at 9090 by hand.

A rule has no effect#

• The host is not decrypted. Map Local, Map Remote, Rewrite, Breakpoints and Scripting can only act on HTTPS they can read. On the Mac, the Tools pane says when a rule points at a host that is not on the list.
• A master switch is off. SSL Proxying and Breakpoints each have one (Breakpoints enabled on Android).
• The rule is past the free plan's limit and has been switched off. The rule list shows this, and Pro turns it back on. See Licenses.
• The pattern does not match. Test it against the flow's full URL, scheme included. Every rule pane on the Mac has a tester, and Android's Breakpoints screen has Test a URL.

A breakpoint left my app hanging#

That is what a breakpoint does: it holds the request until you act. Every rule has a wait, and a forgotten pause ends when it runs out.

• Mac: open Waiting Traffic (⇧⌘B) and execute or abort it.
• iPhone and iPad: Tools ▸ Waiting Breakpoints, or the buttons on the notification.
• Android: Continue, Abort or +1 min on the notification, or Tools ▸ Waiting Breakpoints.

A DNS Spoof rule makes the host hang on iPhone#

The address is one the device cannot reach, 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#

Large bodies are kept truncated and marked that way.

• Mac: raise Body capture limit in Settings ▸ Capture.
• iPhone and iPad: raise Settings ▸ Capture ▸ Body Capture Limit, up to 25 MB per request and per response.
• Android: bodies are kept in full up to 512 MB each.

Pro features stopped working#

• 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.
• The purchaser released this Mac or replaced its key in License Manager.
• A workspace Admin revoked this Mac under Devices in Team Workspace.
• The Mac was signed out after unusual activity on its seat. Sign in again under Settings ▸ License.
• The Team Cloud subscription lapsed.
• On a phone, the App Store or Google Play subscription ended, or the WireLens key was removed or replaced on another device.

See Licenses 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.

If your shell says command not found instead, wirelens is not linked yet: see Install.

On Android#

Most apps stay as tunnels after I decrypt them#

Since Android 7, apps trust certificates you install only when their developer opts in. Browsers such as Chrome do. Most other apps refuse the WireLens certificate, show as connections without requests, and Keep apps working passes them through. Your own app can opt in for debug builds with a network security config:

<network-security-config>
  <debug-overrides>
    <trust-anchors>
      <certificates src="user" />
    </trust-anchors>
  </debug-overrides>
</network-security-config>

Hosts that refused the certificate are listed in Tools ▸ SSL Proxying under Refused the certificate. After changing your app, tap Try decrypting them again. See Things Android decides.

Android will not install the certificate#

Android installs a CA certificate only on a device with a screen lock, and asks you to set one if there is none. Install it as a CA certificate under Security & privacy ▸ More security & privacy ▸ Encryption & credentials ▸ Install a certificate. Some devices put it under Biometrics and security ▸ Other security settings, and searching Settings for "CA certificate" finds it on any device. The setup guide's Open Security Settings opens the right screen on most devices.

Capture stops when I turn on another VPN#

Android runs one VPN at a time, and WireLens captures through a local VPN on the device. Starting another VPN stops WireLens capture. Turn the other VPN off, then start capture again.

Breakpoints never show up#

Breakpoints reach you as notifications. Allow them in step 4 of Settings ▸ Setup Guide, and check that Breakpoints enabled is on in Tools ▸ Breakpoints.

Still stuck#

• On the Mac, choose Help ▸ Report a Bug… or click the bug button in the status bar. You can attach the debug log, which is anonymized on your Mac first.
• From anywhere, use the form at wirelens.app/support, which takes attachments, or write to support@wirelens.app. On Android, Settings ▸ Contact Support starts that email.

Say which device and OS version you use, your WireLens version, and what you expected to happen. On the Mac, Help ▸ Troubleshooting ▸ Copy Diagnostics Report copies a report to paste into a message. Do not send us your license key in full.