When something does not look right

Address already in use on port 4445 or 8087

Another process is bound to one of the tunnel's local ports. Identify it with lsof -i :4445 on macOS or Linux, or netstat -ano | findstr :4445 on Windows. Stop the offending process or change the tunnel's local ports with --se-port 4446 and --localproxy 8088.

--doctor reports "Cannot connect to hub.testingbot.com:443"

The tunnel cannot reach TestingBot. Verify outbound port 443 to *.testingbot.com is open. If you are behind a corporate proxy, route tunnel traffic through it with --proxy host:port and --proxy-userpwd user:password. See the upstream proxy guide.

Authentication failed: 401 Unauthorized

Your TestingBot key or secret is wrong, swapped, or has been rotated. Copy them again from your account settings. If you use environment variables, make sure TESTINGBOT_KEY and TESTINGBOT_SECRET are exported in the same shell that runs the tunnel.

SSL handshake fails inside the cloud browser

Your test target uses certificate pinning or a non-standard CA chain. Either download the TestingBot CA certificate and add it to the trust store on the cloud VM, or disable SSL bumping with the --nobump flag.

WebSocket connection fails or upgrades hang

WebSocket and SSE proxying requires both --nobump and --nocache to be set. The local caching proxy and the SSL-bumping interceptor cannot forward streaming protocols, so they must be disabled. These flags are prerequisites, not optional fix-it switches.

Tests are unusually slow through the tunnel

Bypass non-essential domains with --fast-fail-regexps. A typical setting like the one below often halves the proxied request count:

java -jar testingbot-tunnel.jar -F ".*google-analytics\.com.*,.*facebook\.com.*,.*doubleclick\.net.*"

If your network has limited bandwidth, run multiple tunnels in parallel on different machines and let TestingBot load-balance across them.

Tunnel disconnects every few minutes

A firewall or NAT is killing idle connections. Watch the connection counters at http://localhost:8003 to see reconnect frequency, as covered in the monitoring guide. If JVM memory is the cause, increase the heap:

java -Xmx2g -jar testingbot-tunnel.jar key secret

Java version error: "class file has wrong version"

TestingBot Tunnel 4.x requires Java 11 or higher. Java 8 is no longer supported. Verify with java -version and install Java 17 LTS if needed. See the installation guide.

localhost works on desktop VMs but not on mobile devices

Mobile simulators, emulators and physical devices cannot resolve the literal hostname localhost. Add a custom hostname to /etc/hosts on the tunnel host, such as 127.0.0.1 mywebsite.local, and reference http://mywebsite.local in your tests.

Tunnel shows as active in dashboard after I stopped it

The tunnel was terminated abruptly (kill -9 or hard machine shutdown) and could not deregister itself. Wait up to 5 minutes for the TestingBot grid to time it out, or shut down gracefully next time: press Ctrl+C, delete ~/.testingbot-tunnel.pid, or send kill -SIGUSR1 <pid>.