Troubleshooting
No requests appear
Section titled “No requests appear”The list says No requests yet.
- Check the device’s Wi-Fi proxy: server and port as shown on the address button.
- The device and the computer have to be on the same network. zhttp only accepts devices on private addresses such as
192.168.x.xor10.x.x.x. - The session’s tab light should be mint. Grey means it’s paused: click resume in the top bar.
- A firewall on the computer may be blocking the port.
Client rejected the proxy
Section titled “Client rejected the proxy”A connection fails, and its TLS tab shows Client rejected the proxy with a Likely cause.
Every app fails: the device doesn’t trust the certificate yet. Do steps 2 to 4 of Capture a device. On iOS the last step, full trust under Certificate Trust Settings, is the one most often missed.
One app fails while others work: that app pins its certificate and won’t accept any other. Turn SSL proxying off for its host: click the lock beside the host in Structure. Its traffic then goes through untouched, still listed as connections. See SSL proxying.
To find which hosts fail, look for faint ERR rows, or ask an AI agent to list connections that failed their handshake.
Server handshake failed
Section titled “Server handshake failed”The TLS tab shows Server handshake failed. The Likely cause line says why:
| Likely cause | What to do |
|---|---|
| The server refused the handshake with an alert | The server rejected the hello, and the same alert went to the app. Compare fingerprints in the TLS tab. |
| The server’s certificate did not verify on this machine | The server is self-signed or uses a private CA. The engine in a terminal can skip the check with -insecure. |
| The server chose a key exchange group, or something the client offered, that zhttp can’t complete | Turn SSL proxying off for the host, so the app’s own TLS reaches the server. |
| The server asked for a client certificate, and none is kept for this host | Add the certificate under Client certificates, or turn SSL proxying off for the host so the app answers itself. |
The setup page won’t open
Section titled “The setup page won’t open”Open it with http://, not https://, for example http://zhttp.test/ssl or http://192.168.1.20:8877. Before the certificate is trusted, the HTTPS version can’t load. zhttp.test only works while the device is using zhttp as its proxy.
Port could not be opened
Section titled “Port could not be opened”The tab light is red and the list says Port 8877 could not be opened. Another program has the port. Close it, or close the session and start a new one on a free port. See Sessions and ports.
The proxy engine is not running
Section titled “The proxy engine is not running”The window shows this with the reason underneath. Restart zhttp.
A mapped URL returns 502
Section titled “A mapped URL returns 502”The file it maps to can’t be read. The response body gives the reason. Check the path under the rule, or click Choose… to pick the file again. See Map to file.
Copy as code copies nothing
Section titled “Copy as code copies nothing”A message at the bottom right of the window says The request body is binary and cannot be copied as code. Code can’t carry a binary body. Use Save request body… instead.
A body can’t be edited
Section titled “A body can’t be edited”At a breakpoint or in the composer, a body over 64 MB, or one that isn’t text, can’t be edited. It’s sent on unchanged.