Diagnosing BrowserStack Local Tunnel Connection Failures for Selenium Tests

Recognizable condition

When running Selenium tests that rely on BrowserStack Local, the console or logs show messages such as "Unable to connect to BrowserStack Local" or the test times out while trying to reach a local application.

Cause / diagnostic table

Symptom	Likely cause
Timeout or "Unable to connect"	Firewall blocking outbound 443/80, missing/incorrect access key, outdated Local binary, proxy misconfiguration, TLS trust issue
Immediate "Connection refused"	Local binary not reachable (wrong host/port) or process crashed
Repeated TLS handshake errors in verbose logs	System does not trust BrowserStack’s root CA

Ordered checks

1. Verify credentials

   Ensure BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY are set in the environment where the Local binary and tests run.

   # Example (replace placeholders)
   export BROWSERSTACK_USERNAME="your-user"
   export BROWSERSTACK_ACCESS_KEY="your-key"
   

   Required permission: read access to the environment variables; no special OS privileges.

   Risk: exposing the key in plain text or logs – use secret‑masking in CI.

2. Check outbound network access

   Confirm that the host can open TCP connections to bs-local.com (or *.browserstack.com) on ports 443 and 80.

   # From the test machine
   nc -zv bs-local.com 443
   nc -zv bs-local.com 80
   

   Expected: "Connection to bs-local.com 443 port [tcp/*] succeeded!".

   Limitation: Some corporate proxies intercept TCP; the test may succeed but TLS still fails.

3. Validate Local binary version

   Run the binary with the version flag and compare to the latest version shown in the BrowserStack dashboard.

   BrowserStackLocal --version
   

   If the version is older, download the current release from the dashboard and replace the executable.

4. Inspect proxy configuration (if applicable)

   When behind a proxy, pass the appropriate arguments or set proxy environment variables.

   BrowserStackLocal --key $BROWSERSTACK_ACCESS_KEY \
       --proxyHost proxy.example.com --proxyPort 3128 \
       --proxyUser proxyUser --proxyPass proxyPassword
   

   Alternatively, export HTTP_PROXY and HTTPS_PROXY before starting the binary.

5. Enable verbose logging and examine TLS handshake

   Start Local with -v (or --verbose) and look for handshake errors.

   BrowserStackLocal -v
   

   Successful connection ends with a line similar to:

   Successfully connected to BrowserStack Local

   If you see "SSLHandshakeException" or "certificate_unknown", verify that the system trusts BrowserStack’s root CA (e.g., update the Java truststore or OS CA bundle).

Fixes tied to findings

• Wrong or missing credentials – re‑export the correct BROWSERSTACK_USERNAME and BROWSERSTACK_ACCESS_KEY; ensure CI masks the values.
• Firewall blocks – open outbound TCP 443 and 80 to *.browserstack.com; test with nc or telnet as shown above.
• Outdated Local binary – download the latest BrowserStackLocal binary from the BrowserStack Automate → Local Testing page, replace the existing file, and make it executable (chmod +x BrowserStackLocal).
• Proxy misconfiguration – supply --proxyHost, --proxyPort, --proxyUser, --proxyPass or set HTTP_PROXY/HTTPS_PROXY before launching the binary.
• TLS trust failure – add BrowserStack’s root CA to the trusted store:
  • Linux: sudo cp DigiCertGlobalRootCA.crt /usr/local/share/ca-certificates/ && sudo update-ca-certificates
  • Java: import into $JAVA_HOME/lib/security/cacerts with keytool.

Escalation criteria

Contact BrowserStack support when:

1. The Local binary crashes with a core dump or segfault.
2. Verbose logs repeatedly show "Connection refused" after confirming network access and correct credentials.
3. The issue reproduces on multiple machines and different networks.
4. Logs contain "Invalid access key" despite verified credentials, suggesting a possible account suspension or key revocation.

Limitations and practical verification

This guide covers the most frequent tunnel‑setup problems; it does not address account‑level issues such as concurrency limits or regional service outages.

To confirm that the tunnel is working after applying a fix:

1. Run a minimal Selenium test that opens http://www.google.com and asserts the page title.
2. In the BrowserStack Automate dashboard, navigate to Local Testing; a green "Connected" label next to your Local instance indicates an active tunnel.
3. Check the Local process output for the line "Successfully connected to BrowserStack Local" without any TLS errors.

Note: Never commit your BrowserStack access key to source control; use CI secret stores or environment variables with masking. Run the Local binary under a non‑root user to limit the impact of any potential vulnerability.