Try 25 MB of US mobile proxy data free for 30 days.Start free trial
November 8, 202614 min read

Selenium Grid Proxy: Setup, Auth and Debugging Guide

Isometric platforms linked by a proxy route

A proxy in a Selenium Grid setup is set per browser session, through the proxy capability or a browser flag, and it takes effect on the Node that runs the browser. Grid itself does not route your page traffic through a proxy. It only routes WebDriver commands to browsers. So the Node, not your test machine, must be able to reach the proxy, and any credentials must be handled in a way the browser accepts.

This guide covers where to apply proxy settings, how to do it in Python and JavaScript, what changes with Docker Nodes, how to deal with authenticated proxies, and how to diagnose failures.

TL;DR

  • Grid routes WebDriver sessions to browsers. A proxy routes the browser's page traffic. They are separate layers, and you configure each on its own.
  • Pass the proxy in the session capabilities, and make sure every Node that may pick up the session can reach the proxy host and port.
  • Chrome does not accept credentials embedded in the proxy URL in the setup the Docker guide describes. Use a PAC file or a local forwarder that holds the credentials.
  • With Docker, build arguments only affect the image build. Runtime browser traffic needs runtime proxy settings.
  • When a session stalls, check Chrome's proxy diagnostics, the Grid session timeout and the WebSocket settings before you blame the proxy provider.

Table of Contents

What a proxy does in a Grid setup

Selenium Grid is an HTTP WebDriver server. With RemoteWebDriver, your browser options are sent to the remote Grid instead of starting a local browser, and the Grid routes the session to a managed browser. Your test script talks to the Hub or Router. The browser sits on a Node and talks to the websites.

That gives you two network paths:

  1. Control path: test script to Grid to Node to browser driver. This carries WebDriver commands.
  2. Traffic path: browser to proxy to target site. This carries the pages, API calls and assets you want to fetch.

A proxy only changes the second path. If you point your script at a proxy and not the browser, nothing happens to the traffic that matters. If you point the Grid control path through a corporate proxy by mistake, you may break session creation instead.

This split explains most of the confusion in forum threads on the topic. Settings that work on your laptop run a local browser on your network. On a Grid, the browser runs somewhere else, with its own DNS, firewall and routes.

Why teams add a proxy to Grid at all

The usual reasons fall into three groups:

  • Corporate egress: Nodes sit behind a firewall and must go out through an approved proxy.
  • Geo-targeted checks: you need pages as a visitor in a given city would see them, for local search testing, price comparison or ad verification.
  • Scraping and automation at scale: many parallel browsers should not share one IP address. Datacenter ranges are easier for sites to flag, which is why many teams use real mobile carrier IPs for this work.

The second and third groups are where we spend most of our time. We will come back to them after the mechanics.

Where to apply proxy settings

There are four places a proxy setting can live. Pick one on purpose, and know which of the others may override it.

LayerWhat it controlsUse it when
Session capability (proxy)Browser traffic for one sessionDifferent sessions need different exits, such as different cities
Browser argument (--proxy-server)Chrome's proxy for that launchYou need Chrome-specific behavior or a PAC file
Node or container environmentDefaults for everything on that NodeThe whole Node must use one egress path
Operating system or system proxyWhatever the browser inheritsYou deliberately want the browser to follow the machine

For most test and scraping setups, the session capability is the right layer. It travels with the session request, so the same Grid can serve different proxy settings to different tests.

One rule from the Grid CLI documentation matters here: custom capabilities used to target specific Nodes must be configured on all relevant Nodes and included in every session request. If you split Nodes into pools, for example one pool behind a corporate proxy and one without, tag them with a custom capability and request it every time.

Configure the proxy in your test code

Python

Selenium's Python Proxy class exposes manual HTTP, HTTPS/SSL, SOCKS, PAC, system and bypass fields, plus SOCKS username, password and version. The class documents that you set the HTTP/SSL and no-proxy fields, or the SOCKS fields and version, and to_capabilities() converts those settings into capabilities.

A minimal pattern for a remote session looks like this:

from selenium import webdriver
from selenium.webdriver.common.proxy import Proxy, ProxyType

proxy = Proxy()
proxy.proxy_type = ProxyType.MANUAL
proxy.http_proxy = "proxy.example.com:8080"
proxy.ssl_proxy = "proxy.example.com:8080"
proxy.no_proxy = "localhost,127.0.0.1"

options = webdriver.ChromeOptions()
options.proxy = proxy

driver = webdriver.Remote(
    command_executor="http://grid-hub:4444",
    options=options,
)

Replace the host names with your own. Setting both the HTTP and SSL fields matters: if you set only one, HTTPS pages may leave the proxy and exit from the Node's own address.

JavaScript

In the JavaScript bindings, the manual proxy options http, https and bypass map to the WebDriver fields httpProxy, sslProxy and noProxy. The same API supports PAC configuration through proxy.pac(url) and the system proxy through proxy.system, as the Selenium JavaScript proxy source shows. SOCKS proxies take a host-and-port string and an optional SOCKS version.

Chrome flags

Chrome also accepts the proxy as a command-line argument. In the Docker guide, Chrome's command-line configuration uses separate HTTP and HTTPS proxy values, as the docker-selenium corporate proxy page shows. For the full set of switches and how they interact with bypass rules, see our guide to Chrome proxy flags.

Choosing the protocol

HTTP and HTTPS proxies suit most page-level automation. SOCKS5 is useful when you want the proxy to handle name resolution as well, which affects whether DNS lookups leak from the Node. Our notes on HTTP versus HTTPS proxies and on DNS leaks and SOCKS5 go through the decision in detail.

Docker Nodes: build time versus run time

Selenium's documentation recommends the project's official Docker images, which package Grid, browser and driver, and it supports standalone, Compose and Kubernetes patterns. That is why most teams meet the proxy question in a container.

The most common mistake is putting the proxy in the wrong phase. The Docker guide separates build arguments, used when building the Chrome image, from the proxy settings used when running Chrome. Build arguments do not configure runtime browser traffic. If your image downloads packages through a proxy at build time and then your tests still go out directly, this is the reason.

A short checklist for containerized Nodes:

  1. Decide whether the proxy is needed at build time, run time or both.
  2. For run time, set it per session in capabilities, or pass the browser argument to the Node.
  3. Confirm the container can resolve and reach the proxy host. A proxy at 127.0.0.1 on your laptop is not reachable from inside a container, because the loopback address belongs to the container.
  4. Check the environment variable reference for Node session limits and registration settings. The official environment variable list documents SE_OPTS, Node session limits and registration settings.

If you run Docker-backed Nodes from a TOML file, the Grid TOML options include a [docker] section with image-to-stereotype mappings and the Docker daemon URL. The Grid CLI also documents Docker host, port and URL options, listed in the CLI reference.

Authenticated proxies

Most commercial proxies need a username and password. This is where Chrome and Selenium disagree most with what people expect.

In the setup the Docker guide describes, credentials embedded in the proxy URL do not work with Chrome. The guide recommends a PAC file or a local forwarder that holds the credentials, so the browser talks to an unauthenticated local endpoint and the forwarder adds the authentication upstream.

Your options, in the order we would try them:

  • Local forwarder next to the Node. A small process on the Node (or a sidecar container) listens on a local port without auth and forwards to the upstream proxy with credentials. Chrome points at the local port.
  • PAC file. Host a PAC file that returns the proxy for the traffic you want routed. Pass its URL through the PAC field of the proxy capability.
  • SOCKS with credentials. The Python Proxy class exposes SOCKS username and password fields, and the JavaScript API documents a user, password, host and port string for SOCKS. Browser support for SOCKS authentication varies, so test it on the exact browser and version your Nodes run.

Whichever route you choose, keep credentials out of test code and image layers. Inject them as secrets at run time. In Masklabs, credentials are managed per team in your account, so you can issue separate credentials for each CI pipeline or project and rotate them without touching your images.

Parallel sessions across Nodes

Grid's value is parallelism, and parallelism is where proxy design pays off.

Every session carries its own proxy. Because the proxy capability is part of the session request, ten parallel sessions can use ten different exits. You do not need ten Nodes with ten configurations.

Decide between rotating and sticky sessions. A rotating setup gives each request or connection a new IP, which suits broad collection where continuity does not matter. A sticky session keeps one IP for the life of a flow, which suits logins, carts and multi-step checks where a changing IP would break the session. Match the mode to the test, not to the whole Grid.

Keep concurrency within your data plan. Browsers load much more than HTML: scripts, images and fonts all count when billing is metered per byte. Block heavy assets you do not need, and size your parallel session count to your data pool.

Target specific Nodes with capabilities. If only some Nodes can reach the proxy, use the custom capability approach from earlier so sessions never land on a Node without a route.

Parallel sessions across Nodes

Verify the session is using the proxy

Do not assume a configured proxy is an active proxy. Add a verification step to the first test in every pipeline.

  1. Check the exit IP. Open an IP echo page from inside the session and compare the address with the Node's own egress address. They should differ.
  2. Check the location. For geo-targeted work, confirm that the IP's city or region matches the exit you requested. IP geolocation databases disagree at the city level, so check against more than one before you treat a mismatch as a failure.
  3. Check the headers your session sends. A free HTTP headers checker shows which request and response headers a page sees, which helps confirm that your browser options behave the same as a normal visit.
  4. Test rotation. Run several sessions in a row and confirm the IP changes when you expect it to and stays constant when you use sticky mode. Our list of proxy checker tools covers ways to measure rotation and speed.
  5. Test from the command line first. If the proxy fails in the browser, run the same credentials through curl from the Node. Our curl proxy commands show how to separate DNS problems from authentication problems.

Make this check part of the test setup, so a silent fallback to the Node's own IP fails the run instead of polluting your data.

Troubleshooting failed proxy connections

Work from the inside out: browser first, then Node, then Grid.

Check what Chrome thinks the proxy is

Chrome's debugging guidance says chrome://net-internals/#proxy shows the effective and original proxy settings, and can reveal overrides from flags, extensions, system settings or other software. The Docker guide also points to chrome://net-internals/proxyservice#proxy for debugging. Clearing bad proxies and reapplying the settings there can be part of reproducing a failure.

For resolution failures, Chrome's networking documentation recommends NetLog: capture a reproduction, inspect the Proxy and Events tabs, and filter for PROXY_, PAC_ and WPAD_ events.

Common symptoms

SymptomLikely causeWhat to do
Session starts, traffic exits from the Node's own IPProxy set on the wrong layer, or only HTTP set and not SSLSet both HTTP and SSL fields, then re-run the IP check
HTTP 407 or an auth dialogCredentials embedded in the URL, which Chrome does not accept in the described setupUse a local forwarder or PAC file
Connection refused or timeout from a containerProxy address is a loopback address on the hostUse an address the container can route to
Session works locally, fails on GridNode network differs from your machineTest the proxy with curl from the Node
Session dies after a pauseGrid session timeoutReview the timeout settings below
CDP or BiDi features failWebSocket traffic blockedReview the WebSocket settings below

Grid-level settings that look like proxy failures

The Grid CLI documents a default session timeout of 300 seconds, along with Node registration timing options. A proxied page that loads slowly can look like a dead proxy when the Grid has simply reclaimed an idle session. The same reference documents a per-session WebSocket connection limit and options for enabling or disabling CDP and BiDi proxying, and notes these features may be disabled if the network does not allow WebSockets. All of this is in the Grid CLI options page.

Version-specific bugs

One reported Selenium 4.11 Docker failure involved a proxy capability passed as a map where Selenium Manager expected a Proxy object. A Selenium contributor said it should have been fixed in 4.12. If you see a startup error that mentions the proxy type, check your Selenium version before changing anything else. For Java teams, our Java proxy scraping configs cover the 407 and throttling cases in detail.

Our view: match the exit to the job

Most Grid proxy problems we see are not proxy problems. They are placement problems: the setting is on the wrong layer, in the wrong build phase, or on a Node that cannot reach the exit. Fix the plumbing first and everything else gets simpler.

Once the plumbing works, the quality of the exit decides the quality of your data. Datacenter addresses are easy for sites to recognize, and requests from them are more likely to be blocked or throttled. We built Masklabs on real US carrier IPs instead, with city-level targeting across 46 US cities, so a session that needs to look like a visitor in a given city can do that. Our sticky and rotating modes let you pick per session, which is how a Grid should be used.

We also think setup should not need a sales call. You create credentials in the dashboard, assign them to a team, watch usage in real time and pay by the byte. That fits the way Grid runs: many short sessions, each with a clear job, and a budget you can see.

Jon

Using Masklabs with your Grid

Masklabs gives your Grid real carrier IPs from US mobile networks, with HTTP, HTTPS and SOCKS5 support and an API you can call from Python, Node.js, Java, C#, Rust or browser automation. Our own claims are approximately 99.9% uptime and a success rate above 99%, and you can see usage per credential in the dashboard.

Plans are subscriptions based on monthly data pool size: Starter is $30.00 per month, Basic is $100.00, Advanced is $500.00 and Scale is $1,000.00. You can add prepaid data billed per GB, and there is a free trial with limited data, so you can run the verification steps above on a real Node before you commit. See the current plans for what each pool includes.

Masklabs

If you are wiring this into a test suite, our guide to a Selenium proxy for automated testing teams shows the team setup. For wider tool choices, see the headless browser tools list. You can start from the Masklabs home page and create credentials in minutes.

FAQ

Does Selenium Grid have a built-in proxy setting?

Grid routes WebDriver sessions to browsers, so it does not proxy your page traffic by itself. You set the proxy per session through the proxy capability or a browser argument. The browser on the Node then sends its traffic through that proxy.

Why does my proxy work locally but not on the Grid?

On a Grid, the browser runs on the Node, with the Node's network, DNS and firewall. The proxy host must be reachable from there. Test it with curl on the Node, and avoid loopback addresses when the Node runs in a container.

How do I use a username and password proxy with Chrome on Grid?

Do not embed the credentials in the proxy URL, because Chrome does not accept that in the setup the Docker guide describes. Use a local forwarder that holds the credentials, or a PAC file. Inject the credentials as run-time secrets.

Can different parallel sessions use different proxies?

Yes. The proxy capability is part of each session request, so each session can use its own exit. If only some Nodes can reach a given proxy, tag those Nodes with a custom capability and request it in every session.

How do I confirm a session is actually proxied?

Open an IP echo page inside the session and compare the address to the Node's own egress IP. For geo-targeted work, confirm the location too. Run the check at the start of every pipeline.

Sources

Recommended