---
title: Troubleshooting the Tunnel | TestingBot
description: 'A tunnel has more moving parts than a plain cloud test: your machine,
  your network&#39;s firewall and proxy, the tunnel server, the cloud browser or device,…'
source_url:
  html: https://testingbot.com/resources/courses/local-website-testing/troubleshooting
  md: https://testingbot.com/resources/courses/local-website-testing/troubleshooting.md
---

Course

[Local Testing with a Secure Tunnel](https://testingbot.com/resources/courses/local-website-testing)

Chapter 6 of 7

1. [1 Learn about Local Testing](https://testingbot.com/resources/courses/local-website-testing)
2. [2 Setting up TestingBot Tunnel](https://testingbot.com/resources/courses/local-website-testing/setting-up-testingbot-tunnel)
3. [3 Example test with Tunnel](https://testingbot.com/resources/courses/local-website-testing/example-tunnel-test)
4. [4 Tunnel CLI Arguments](https://testingbot.com/resources/courses/local-website-testing/cli-arguments)
5. [5 Manual Testing Private Websites](https://testingbot.com/resources/courses/local-website-testing/manual-testing-tunnel)
6. [6 Troubleshooting the Tunnel](https://testingbot.com/resources/courses/local-website-testing/troubleshooting)
7. [7 Knowledge check](https://testingbot.com/resources/courses/local-website-testing/knowledge-check)

[Exit course](https://testingbot.com/resources/courses)

 Chapter 6 of 7 Beginner 8 min read 3 quick checks Updated Nov 2026 

# Troubleshooting the Tunnel
On this page
1. [Step 1: run --doctor](https://testingbot.com#step-1-run-doctor)
2. [Step 2: decide which side failed](https://testingbot.com#step-2-decide-which-side-failed)
3. [Step 3: read the tunnel's error response](https://testingbot.com#step-3-read-the-tunnel-s-error-response)
4. [Startup problems](https://testingbot.com#startup-problems)
5. [Problems while tests run](https://testingbot.com#problems-while-tests-run)
6. [Step 4: capture a useful log](https://testingbot.com#step-4-capture-a-useful-log)
7. [Asking for help](https://testingbot.com#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`[#](https://testingbot.com#step-1-run-doctor)

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

```bash
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[#](https://testingbot.com#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[#](https://testingbot.com#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?

 The staging server is down The tunnel's `--allow-hosts` list refused the host The cloud browser's DNS cannot resolve internal names The CI runner cannot resolve the name; fix its DNS (for example with `--dns`) or run the tunnel where the name resolves

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[#](https://testingbot.com#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?

 Start the new one with `--se-port 4446 --localproxy 8088` Run `--doctor` until the error disappears Re-enter your key and secret

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[#](https://testingbot.com#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[#](https://testingbot.com#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`):

```bash
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?

 Compare timestamps between the tunnel log and the access log Turn on `forwarder:headers` logging Take the request id from the tunnel log and search your server's access log for the same `X-Request-Id`

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[#](https://testingbot.com#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](https://testingbot.com/support/tunnel/troubleshooting) and the [tunnel FAQ](https://testingbot.com/support/tunnel/faq) cover rarer cases, and the [logging guide](https://testingbot.com/support/tunnel/logging) documents every log option.

[Previous · Chapter 5 Manual Testing Private Websites](https://testingbot.com/resources/courses/local-website-testing/manual-testing-tunnel) [Next · Chapter 7 Knowledge check](https://testingbot.com/resources/courses/local-website-testing/knowledge-check)

On this page

1. [Step 1: run --doctor](https://testingbot.com#step-1-run-doctor)
2. [Step 2: decide which side failed](https://testingbot.com#step-2-decide-which-side-failed)
3. [Step 3: read the tunnel's error response](https://testingbot.com#step-3-read-the-tunnel-s-error-response)
4. [Startup problems](https://testingbot.com#startup-problems)
5. [Problems while tests run](https://testingbot.com#problems-while-tests-run)
6. [Step 4: capture a useful log](https://testingbot.com#step-4-capture-a-useful-log)
7. [Asking for help](https://testingbot.com#asking-for-help)

Certification

Earn the free, resume-worthy TestingBot Local Testing Certification for this course.

[How it works](https://testingbot.com/resources/courses/local-website-testing/certification)
