Exit course
Chapter 6 of 7 Beginner 8 min read 3 quick checks Updated

Troubleshooting the Tunnel

On this page
  1. Step 1: run --doctor
  2. Step 2: decide which side failed
  3. Step 3: read the tunnel's error response
  4. Startup problems
  5. Problems while tests run
  6. Step 4: capture a useful log
  7. Asking for help

A tunnel has more moving parts than a plain cloud test: your machine, your network's firewall and proxy, the tunnel server, the cloud browser or device, and the site you are testing. When a local test fails, the first job is to find out which of those parts failed. This chapter gives you a fixed order to check things in, shows how to read the tunnel's own error messages, and covers the problems that come up most often.

Step 1: run --doctor #

Before reading any logs, run the diagnostics with the same options you start the tunnel with:

java -jar testingbot-tunnel.jar --doctor --proxy proxy.corp:8080

It checks DNS, connectivity to TestingBot, that the local ports are free, and any upstream proxy, Kerberos or extra CA settings you passed. It exits non-zero on failure. Most "the tunnel never starts" problems are answered here in seconds.

Step 2: decide which side failed#

Ask two questions:

  1. Did the tunnel print You may start your tests? If not, the problem is between the tunnel and TestingBot: credentials, Java, ports or the outbound network. Look at the startup problems below.
  2. Does the page load in a browser on the tunnel machine? If not, the problem is the site or the URL, not the tunnel. Fix that first.

If both answers are yes and the cloud browser still cannot load the page, the problem is in how the request travels through the tunnel, and the tunnel will tell you why.

Step 3: read the tunnel's error response#

When the tunnel cannot or will not complete a request, it answers the cloud browser with an HTTP status, an X-TestingBot-Error response header, and a one-line explanation that appears in the browser window. In a manual session you read it on screen; in an automated test, take a screenshot or look at the session video.

X-TestingBot-Error Status Meaning
not-allowed 403 The host is not in --allow-hosts.
denied-by-fast-fail 403 Blocked by --fast-fail-regexps.
denied-localhost 403 Blocked by --localhost-policy deny.
dns-error 502 The tunnel machine could not resolve the hostname.
connection-refused 502 Nothing is listening on that port on the target.
connection-timeout 504 Connecting to the target timed out.
host-unreachable 502 The tunnel machine has no network route to the target.
tls-error 502 The TLS handshake with the target failed.
upstream-proxy-* 502 Your upstream proxy was unreachable, rejected the credentials, or refused the destination.

Read the table as a map of where to look. A 403 is your own tunnel configuration doing its job. dns-error, connection-refused and host-unreachable mean the tunnel machine cannot reach the site: check from that machine with curl -v <url>. A common case of connection-refused is a dev server bound to 127.0.0.1 on a different machine from the tunnel, or a dev server that has stopped.

The tunnel runs on a CI runner. A test of https://staging.internal.example gets a 502 with X-TestingBot-Error: dns-error, although the page opens fine on your laptop. Where is the problem?

Names are resolved on the tunnel machine, and your laptop is not that machine. A refused host would be a 403, and a down server would resolve but refuse the connection.

Startup problems#

"Address already in use" on port 4445 or 8087. Another process, often a second tunnel, holds a local port. Find it with lsof -i :4445 (macOS, Linux) or netstat -ano | findstr :4445 (Windows), stop it, or move the tunnel with --se-port 4446 --localproxy 8088.

--doctor cannot connect to TestingBot. Outbound port 443 or 22 to *.testingbot.com is blocked. On a corporate network, route through your proxy with --proxy host:port and --proxy-userpwd user:password, or the TESTINGBOT_PROXY_USERPWD variable.

401 Unauthorized. The key or secret is wrong, swapped or rotated. Copy them again from your account settings, and if you use environment variables, make sure they are exported in the same shell that starts the tunnel.

"class file has wrong version" or "A JNI error has occurred". Tunnel 5.x needs Java 17 or newer. Upgrade Java or switch to a standalone build, which bundles its own runtime.

Starting a tunnel fails with "Address already in use" on port 4445, and you also need the tunnel that is already running. What do you do?

Each tunnel needs its own local ports. Moving the second one to free ports lets both run; the error has nothing to do with credentials, and --doctor only reports the conflict.

Problems while tests run#

The page loads on desktop VMs but not on phones. You used localhost. Mobile devices, simulators and emulators cannot resolve it. Use local.testingbot.com:<port>, or a hostname from /etc/hosts on the tunnel machine.

HTTPS localhost fails with ERR_SSL_PROTOCOL_ERROR. Browsers refuse to send https://localhost through a proxy, so the request never reaches the tunnel. Same fix: https://local.testingbot.com:<port>.

WebSockets or Server-Sent Events never connect. Live reload, chat widgets and real-time dashboards need the tunnel started with both --nobump and --nocache. These are prerequisites for streaming protocols, not optional tuning. Connect to ws://local.testingbot.com:<port> rather than ws://localhost.

Certificate errors in a mobile app. The app pins its certificate and rejects the re-signed one. Add the TestingBot CA to the trust store of your test build, or start the tunnel with --nobump (or --nobump-domains for just the affected hosts).

Pages are slow. Every request, including analytics, ads and fonts from third parties, goes through the tunnel. Refuse the noise with -F '.*google-analytics\.com,.*doubleclick\.net'. If bandwidth is the limit, run several tunnels on different machines with the same --tunnel-identifier and let TestingBot spread sessions across them.

The tunnel disconnects every few minutes. A firewall or NAT is dropping idle connections. Watch the reconnect counters on http://127.0.0.1:8003. If the Java process is short of memory, start it with a larger heap: java -Xmx2g -jar testingbot-tunnel.jar.

The dashboard still shows a tunnel you stopped. It was killed hard (kill -9, a crashed VM) and could not deregister. It times out within five minutes; next time stop it gracefully with Ctrl+C or kill -SIGUSR1 <pid>.

Step 4: capture a useful log#

Since 5.0 the tunnel only logs failed requests by default. When you need the full picture, turn up the part you are debugging. The tunnel carries two kinds of traffic: the proxy (requests the cloud browser makes to your sites) and the forwarder (the Selenium relay on port 4445). You can set each separately. When a page will not load, show browser traffic with headers and hide WebDriver commands; for a WebDriver problem, swap them (proxy:none,forwarder:headers):

java -jar testingbot-tunnel.jar --log-http proxy:headers,forwarder:none --logfile tunnel.log

Each log line carries a request id, which the tunnel also passes to your server in the X-Request-Id header. Search for that id in your application's access log to match a failing browser request to what your server saw. Credentials (authorization headers, cookies, passwords in URLs) are redacted before anything is written, so the log is safe to attach to a ticket.

A form submit fails only through the tunnel, and you want to see what your server received for that exact request. How do you match the two?

The tunnel passes its request id to your server in X-Request-Id, which identifies the request exactly. The forwarder logs WebDriver commands, not the browser's requests to your site.

Asking for help#

If you still need support, send the tunnel version (--version), the --doctor output, a debug log from a failing run, and the exact options you started the tunnel with. The tunnel troubleshooting reference and the tunnel FAQ cover rarer cases, and the logging guide documents every log option.