How to Diagnose ECONNREFUSED Errors in Selenium WebDriver

ECONNREFUSED means the Selenium client reached a host and port, but no process accepted the TCP connection (or the operating system actively rejected it). The fastest fix is to identify the endpoint first: a local WebDriver session should start a browser driver on the test machine; a remote session sends commands to Selenium Server or Grid, commonly at http://localhost:4444.

1. Identify what Selenium is trying to reach

Read the exception and your driver construction code. Record the scheme, hostname, port, and path. Do not assume that localhost means the computer where the browser is running.

Mode	Browser and driver run on	Listener required	Typical target
Local	The test machine	No Selenium Server	Driver process started by the binding
Remote	A Grid node or server	Yes	http://grid-host:4444

JavaScript: check for an unintended remote URL

const { Builder, Browser } = require('selenium-webdriver');

// This is remote mode. It requires a server listening at this URL.
const driver = await new Builder()
  .forBrowser(Browser.CHROME)
  .usingServer(process.env.SELENIUM_REMOTE_URL || 'http://localhost:4444')
  .build();

If the browser should run locally, remove usingServer() and unset SELENIUM_REMOTE_URL:

const { Builder, Browser } = require('selenium-webdriver');
const driver = await new Builder().forBrowser(Browser.CHROME).build();

Python: local and remote construction

from selenium import webdriver
from selenium.webdriver.chrome.options import Options

# Local mode
local = webdriver.Chrome()

# Remote mode (requires Selenium Server/Grid)
options = Options()
remote = webdriver.Remote(
    command_executor="http://localhost:4444",
    options=options,
)

2. Probe the endpoint from the test environment

Run checks from the same container, VM, CI worker, or host that runs the test. A probe from your laptop does not prove that a CI worker can reach the endpoint.

# HTTP probe
curl -v --max-time 5 http://localhost:4444/status

# TCP probe when curl is unavailable
nc -vz localhost 4444

# Check which local process owns the port
ss -ltnp | grep ':4444'

A refusal usually indicates that the server is stopped, still starting, bound to another interface, using another port, or separated by a container network boundary. A timeout points more toward routing or firewall filtering; a successful HTTP response means the problem is later in session creation.

3. Start and verify Selenium Server/Grid

The official standalone Grid setup listens at http://localhost:4444 by default and clients must point RemoteWebDriver there. Follow the Selenium Grid getting-started documentation for the current startup command and Java requirements.

# Example standalone launch after downloading the Selenium Server jar
java -jar selenium-server-<version>.jar standalone

1. Start the server before the test process.
2. Wait for /status to report readiness.
3. Confirm the host, port, scheme, and path match the client exactly.
4. Inspect server logs for bind failures, port conflicts, or startup exceptions.

For a non-default port, configure both sides consistently. For example, if the server binds to port 5555, use http://grid-host:5555 in the client and probe that same address.

4. Check localhost, containers, and CI routing

Inside a container, localhost refers to that container’s network namespace. It does not automatically refer to the host or a second container.

• If the test and Grid are separate containers, use the Grid service name on a shared network, such as http://selenium:4444.
• If the Grid runs on the host, publish the port and use the runtime’s host gateway address where required.
• In CI, verify that the service port is published to the job network.
• Add a health check or readiness loop so the test does not race server startup.

# Simple readiness loop (POSIX shell)
for i in $(seq 1 30); do
  if curl -fsS http://selenium:4444/status >/dev/null; then
    break
  fi
  sleep 1
done
curl -fsS http://selenium:4444/status

5. Separate driver discovery from endpoint refusal

Selenium Manager is Selenium’s official driver manager and has shipped with Selenium releases since 4.6. It can discover an installed browser, resolve a compatible driver, download it, and cache it.

A missing driver normally produces a driver-location or driver-startup error, not a refusal from localhost:4444. Keep the failure classes separate:

Symptom	Likely layer	Next check
ECONNREFUSED host:4444	Selenium Server/Grid endpoint	Probe the URL and inspect Grid startup
Unable to obtain driver	Browser-driver management	Upgrade Selenium, verify browser, PATH, and Selenium Manager
Session created then browser fails	Driver/browser/runtime	Read driver and browser logs

For a current Selenium release, allow Selenium Manager to work automatically. If policy requires a fixed executable, configure the language binding’s Service object or ensure the driver is on PATH. Reinstalling Chrome alone will not make a refused Grid port accept connections.

6. Diagnose Selenium Manager proxy and firewall failures

Selenium Manager makes outbound requests for browser and driver metadata. Its documented connectivity problems include proxy or firewall restrictions, DNS lookup failures, and forcibly closed connections.

Configure the proxy using the supported --proxy option, the SE_PROXY environment variable, or Selenium Manager’s configuration file. Make sure CI policy permits DNS and HTTPS access to the required metadata and download hosts. These outbound failures are different from a local Grid refusal: one concerns Selenium Manager’s downloads, the other concerns a listener accepting WebDriver commands.

# Inspect proxy variables in a CI job
env | grep -iE '^(http|https|no)_proxy='

# Selenium Manager proxy configuration example
export SE_PROXY=http://proxy.example:8080

7. A repeatable diagnosis checklist

1. Copy the refused URL from the exception.
2. Search code and environment for usingServer, RemoteWebDriver, or SELENIUM_REMOTE_URL.
3. Decide whether the test should be local or remote.
4. Probe the exact host and port from the test runtime.
5. Check the Grid process, bind address, configured port, and logs.
6. For containers, verify service names, shared networks, and published ports.
7. Wait for readiness before creating the first session.
8. Only after endpoint reachability is proven, investigate Selenium Manager, browser, and driver errors.
9. For proxy failures, configure SE_PROXY or --proxy and verify DNS/firewall policy.

8. Common errors and fixes

Error or symptom	Cause	Fix
Connection refused: localhost:4444	No Grid listener on that namespace and port	Start Grid, correct the URL, or remove unintended remote mode
Refusal only in CI	Different network namespace or startup race	Probe inside the worker, publish the port, and add readiness checks
Refusal after changing ports	Client and server use different ports	Make the configured port identical and recheck logs
Timeout instead of refusal	Routing or firewall silently drops traffic	Check routes, security groups, and firewall rules from the worker
Driver-location error	Driver is unavailable or incompatible	Upgrade Selenium, verify browser installation and PATH, or configure Service
Selenium Manager download failure	Proxy, DNS, firewall, or closed outbound connection	Set SE_PROXY/--proxy and allow required outbound traffic
Works on host, fails in container	localhost points to the container	Use the service name, host gateway, or published address

9. Performance, reliability, and cost considerations

Endpoint checks add little work compared with a browser session, but avoid probing indefinitely. Use a bounded readiness loop and fail with the resolved URL, namespace, and last server log lines. Reuse a correctly configured Grid for a test batch instead of starting a new server per test. Cache browser and driver downloads in CI where policy allows; this reduces startup time without changing endpoint diagnosis.

Remote execution adds network latency and another process that can fail. Keep Grid and workers close to the test runner, set explicit session timeouts, and collect server, driver, and browser logs together. A refused TCP connection does not consume browser time or indicate a Selenium licensing charge; it is an availability failure before a session exists.

10. Or skip the browser setup

If your goal is a clean image or PDF of a URL rather than interactive browser automation, ScreenshotNeo provides a single HTTP request. Its capture service removes cookie and consent banners, newsletter popups, and chat widgets before the shot. Bot checks, blank pages, timeouts, failed loads, and cache hits are not billed, and response headers report the page verdict and billing status.

See the ScreenshotNeo API documentation for all options.

curl -G "https://api.screenshotneo.com/v1/shot" \
  -d access_key=YOUR_API_KEY \
  --data-urlencode url=https://stripe.com \
  -o shot.webp

import requests
r = requests.get(
    "https://api.screenshotneo.com/v1/shot",
    params={"access_key": "YOUR_API_KEY", "url": "https://stripe.com"},
    timeout=90,
)
r.raise_for_status()
open("shot.webp", "wb").write(r.content)

const q = new URLSearchParams({ access_key: 'YOUR_API_KEY', url: 'https://stripe.com' });
const res = await fetch(`https://api.screenshotneo.com/v1/shot?${q}`);
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
require('fs').writeFileSync('shot.webp', Buffer.from(await res.arrayBuffer()));

ScreenshotNeo also has an MCP server so Claude, Cursor, and other MCP clients can use take_screenshot, get_page_info, and capture_pdf. One thousand screenshots per month are free with no card; paid plans start at $5 for 3,000 shots. Create a free ScreenshotNeo account.

FAQ

Does ECONNREFUSED mean Chrome is broken?

Usually no. It identifies a refused TCP endpoint. Check the Selenium Server/Grid URL and listener before changing Chrome.

Why does localhost work in one terminal but not CI?

The processes may be in different containers, VMs, or network namespaces. Probe from the CI worker and use a routable service name or published port.

Should I install a driver manually?

Not necessarily. Current Selenium releases include Selenium Manager. Manual PATH or Service configuration is useful when downloads are restricted or a fixed driver is required.

Can a proxy cause ECONNREFUSED?

It can refuse Selenium Manager’s outbound connection, but that is distinct from a refused Grid endpoint. Identify which host and port appears in the error.

What should I log for the next failure?

Log the resolved remote URL, execution environment, probe result, Grid status response, Selenium Server logs, driver logs, and relevant proxy variables without exposing credentials.