--- title: TestingBot Tunnel Troubleshooting - Common Errors and Fixes description: 'Diagnose and fix TestingBot Tunnel issues: port conflicts, --doctor failures, SSL bumping errors, slow speeds, WebSocket problems, disconnects and authentication errors.' source_url: html: https://testingbot.com/support/tunnel/troubleshooting md: https://testingbot.com/support/tunnel/troubleshooting/index.md --- # When something does not look right Most tunnel problems fall into one of four categories: a missing prerequisite, a network or firewall block, a wrong flag combination or a credential mismatch. This page walks through the common symptoms, what causes them, and how to fix them. ## Run --doctor first The built-in health check validates ports, outbound connectivity and credentials in one step. Run it before anything else when something looks wrong. java -jar testingbot-tunnel.jar --doctor `--doctor` exits with a non-zero status if any check fails, which makes it usable as a CI pre-flight step. ## Issues you may encounter ### 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](https://testingbot.com/support/tunnel/upstream-proxy). ### Authentication failed: 401 Unauthorized Your TestingBot key or secret is wrong, swapped, or has been rotated. Copy them again from [your account settings](https://testingbot.com/members/user/edit). 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](https://testingbot.com/downloads/testingbot-ssl-bumping.crt) 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](https://testingbot.com/support/tunnel/multiple) 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](https://testingbot.com/support/tunnel/monitoring). 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](https://testingbot.com/support/tunnel/installation). ### 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 `. ## Reading the logs Re-run the tunnel with `--log-level debug` and `--logfile` to capture detailed output to a file. java -jar testingbot-tunnel.jar --log-level debug --logfile tunnel.log key secret The log file is the first thing support will ask for. `--debug` additionally prints request and response headers, useful when diagnosing application-level issues. ## Contact support If none of the steps above resolve your issue, reach out to [TestingBot support](https://testingbot.com/support/contact) with: - The exact tunnel version (`java -jar testingbot-tunnel.jar --version`). - Your `--doctor` output. - The debug log file from a failing run. - The flags you started the tunnel with. Was this page helpful? Yes No ## Looking for More Help? Have questions or need more information? You can reach us via the following channels: - [Email us](https://testingbot.com/contact/new) - [Join our Slack Channel](https://join.slack.com/t/testingb0t/shared_invite/zt-3bcw9xch-jk19~6XPs_xBrsAgAedkCw)