Puppeteer and Playwright Proxy Setup, Auth and Rotation
Working proxy code for Puppeteer and Playwright in Node and Python: authentication, per-context proxies, SOCKS5 limits, sticky sessions, error fixes.
Puppeteer takes the proxy address as a Chromium launch flag and the credentials in a separate page.authenticate call. Playwright takes both in one proxy object, at launch or per browser context. Neither accepts user:pass@host in the address, and neither can log in to a SOCKS5 proxy with a username and password.
| Puppeteer | Playwright | |
|---|---|---|
| Proxy address | args: ["--proxy-server=http://HOST:PORT"] | proxy: { server: "http://HOST:PORT" } |
| Username and password | page.authenticate({ username, password }) | username and password in the same proxy object |
| A different proxy per context | browser.createBrowserContext({ proxyServer }) | browser.newContext({ proxy }) |
| A different proxy per page | No. Use one context per proxy | No. Use one context per proxy |
| SOCKS5 with a login | Not supported by Chromium | Refused at launch |
| Python API | None | sync_api and async_api, same options |
This page is the technical setup. If you are still choosing a product, proxies for browser automation compares the Node4 plans for headless browsers and shows what each costs.
Before you start
- Node.js 22.12 or later (Puppeteer 25 requires it; Playwright 1.65 needs 20 or later) with
npm install puppeteer, ornpm install playwrightfollowed bynpx playwright install chromium. For Python:pip install playwright, thenplaywright install chromium. - A proxy host, port, username and password. On Node4 they are on the Proxies page of the dashboard. One credential works on every product your account holds a plan for.
- The free plan's 3 shared datacenter proxies work with every HTTP example below. The rotating and residential gateways, and SOCKS5, need a paid plan.
Every sample was run on Puppeteer 25 and Playwright 1.65, in Node and in Python. The error names quoted below are the ones those versions produced.
Puppeteer proxy setup
import puppeteer from "puppeteer";
const browser = await puppeteer.launch({
args: ["--proxy-server=http://HOST:PORT"],
});
const page = await browser.newPage();
await page.authenticate({ username: "USERNAME", password: "PASSWORD" });
const response = await page.goto("https://api.ipify.org/");
console.log(response.status(), await response.text());
await browser.close();Expected output is 200 followed by the proxy's exit address, not your own:
200 203.0.113.47With IP whitelisting instead of a password, drop the page.authenticate line; the flag alone is enough. Whitelisting works on every product, and a whitelisted connection is untargeted, because country and session targeting ride in the username.
Puppeteer proxy authentication with page.authenticate
Chromium connects to the proxy with no credentials, receives a 407 challenge, and asks Puppeteer for the answer. page.authenticate is that answer. What to know about it:
- Call it before the first
goto. Without it, navigation fails withnet::ERR_INVALID_AUTH_CREDENTIALS. - A wrong password does not throw.
gotoresolves normally with a response whosestatus()is407. Check the status before reading the page, or a scraper will happily parse Chrome's error page. - Chromium remembers the login for the whole browser context. After the first page authenticates, every other page in that context reuses the same username, even if you call
page.authenticateon it with a different one. Two pages that need two usernames (two sticky sessions, two countries) need two contexts, shown below. - It turns on request interception behind the scenes, as the Puppeteer documentation notes, so expect a small overhead on every request.
- It covers the whole page. The document, scripts, images, XHR and fetch calls all go out with the same login.
Why Chrome ignores credentials in the proxy URL
--proxy-server=http://USERNAME:PASSWORD@HOST:PORT works in curl and in most HTTP libraries, so it is the first thing people try. Chromium's flag has no syntax for credentials. It rejects the whole value, and navigation fails with net::ERR_NO_SUPPORTED_PROXIES before anything reaches the proxy. Playwright does not read them from the address either: credentials embedded in server are never sent, so the proxy refuses the request.
Keep the address and the login separate in your config, and percent-encoding problems with characters such as @ and : in a password go away too, because neither page.authenticate nor Playwright's password field is parsed as a URL.
A different proxy per browser context in Puppeteer
--proxy-server applies to the whole browser. To run several proxies, or several logins on one gateway, in a single Chromium process, give each its own browser context:
import puppeteer from "puppeteer";
const browser = await puppeteer.launch();
async function openWorker(proxyServer, username) {
const context = await browser.createBrowserContext({ proxyServer });
const page = await context.newPage();
await page.authenticate({ username, password: "PASSWORD" });
return { context, page };
}
const a = await openWorker("http://HOST:PORT", "USERNAME-session-a1");
const b = await openWorker("http://HOST:PORT", "USERNAME-session-b2");
for (const { page } of [a, b]) {
const response = await page.goto("https://api.ipify.org/");
console.log(await response.text());
}
await browser.close();Each context has its own cookies, storage and proxy login, so the two workers make independent pool picks. They usually print two different exits, but two picks can land on the same address, so check isolation by the login each context sends, not by the IPs differing. Credentials still go through page.authenticate; proxyServer takes the address only.
Playwright proxy setup
Playwright answers the proxy challenge itself. There is no per-page call:
import { chromium } from "playwright";
const browser = await chromium.launch({
proxy: {
server: "http://HOST:PORT",
username: "USERNAME",
password: "PASSWORD",
},
});
const page = await browser.newPage();
const response = await page.goto("https://api.ipify.org/");
console.log(response.status(), await response.text());
await browser.close();The same object works with firefox.launch. For the Playwright test runner, put it in the config and every test uses it:
// playwright.config.js
import { defineConfig } from "@playwright/test";
export default defineConfig({
use: {
proxy: {
server: "http://HOST:PORT",
username: process.env.PROXY_USERNAME,
password: process.env.PROXY_PASSWORD,
},
},
});Playwright proxy in Python
The Python API takes the same keys in a dict:
from playwright.sync_api import sync_playwright
with sync_playwright() as p:
browser = p.chromium.launch(
proxy={
"server": "http://HOST:PORT",
"username": "USERNAME",
"password": "PASSWORD",
}
)
page = browser.new_page()
response = page.goto("https://api.ipify.org/")
print(response.status, response.text())
browser.close()Both print 200 and the exit address. For plain HTTP clients rather than browsers, see Python proxy integration and Node.js proxy setup.
Playwright proxy authentication: why a wrong password times out
With wrong or missing credentials, Playwright on Chromium does not report a 407 for an HTTPS page. page.goto waits and then fails with Timeout 30000ms exceeded. On a plain http:// page the same mistake returns a response with status 407. Firefox reports NS_ERROR_PROXY_CONNECTION_REFUSED for both.
So a navigation timeout on the first page through a new proxy is a credentials problem until proven otherwise. Prove it with curl, which prints the status the browser hides:
curl -q --noproxy '' --max-time 30 -v -x http://HOST:PORT -U 'USERNAME:PASSWORD' https://api.ipify.org-q skips any local .curlrc, --noproxy '' stops a NO_PROXY variable from routing around the proxy, and --max-time turns a hang into an error.
If curl also gets a 407, the login itself is refused; fixing 407 Proxy Authentication Required lists the causes in order.
Playwright proxy per page, or per context?
Per context. A page inherits the proxy of the context that created it and cannot have its own. A context is cheap, so open one per proxy:
import { chromium } from "playwright";
const browser = await chromium.launch();
async function openWorker(country, sessionId) {
const context = await browser.newContext({
proxy: {
server: "http://gw-residential.node4.io:8082",
username: `USERNAME-country-${country}-session-${sessionId}`,
password: "PASSWORD",
},
});
return { context, page: await context.newPage() };
}
const us = await openWorker("us", "w1");
const de = await openWorker("de", "w2");
for (const { page } of [us, de]) {
const response = await page.goto("https://api.ipify.org/");
console.log(await response.text());
}
await browser.close();The async Python version, with both contexts working at the same time:
import asyncio
from playwright.async_api import async_playwright
GATEWAY = "http://gw-residential.node4.io:8082"
async def exit_ip(browser, country, session_id):
context = await browser.new_context(
proxy={
"server": GATEWAY,
"username": f"USERNAME-country-{country}-session-{session_id}",
"password": "PASSWORD",
}
)
page = await context.new_page()
response = await page.goto("https://api.ipify.org/")
ip = await response.text()
await context.close()
return ip
async def main():
async with async_playwright() as p:
browser = await p.chromium.launch()
print(await asyncio.gather(
exit_ip(browser, "us", "w1"),
exit_ip(browser, "de", "w2"),
))
await browser.close()
asyncio.run(main())Older guides tell you to launch Chromium with a placeholder such as proxy: { server: "http://per-context" }, because per-context proxies were once ignored on Windows without it. On Playwright 1.65 a bare chromium.launch() honors context proxies on Windows. Keep the placeholder only if you support old releases, and assert that two contexts report two exits either way.
HTTP, HTTPS or SOCKS5: which scheme to use
| You want | Write | Notes |
|---|---|---|
To load https:// sites through a proxy | http://HOST:PORT | The usual case. The browser opens a CONNECT tunnel and the TLS session runs end to end between browser and site; the proxy sees the hostname, not the content |
To load http:// sites | http://HOST:PORT | Same setting |
| SOCKS5 | socks5://HOST:PORT | No username or password possible in Chromium, see below |
A "Puppeteer HTTPS proxy" almost always means the first row: an HTTP proxy carrying HTTPS traffic. Node4 endpoints are http:// proxy URLs. Do not write https:// in front of the host; that asks the browser to speak TLS to the proxy itself.
SOCKS5 in Puppeteer and Playwright
Chromium implements SOCKS5 without the username and password exchange. The practical results:
- Puppeteer:
--proxy-server=socks5://HOST:PORTworks.page.authenticatedoes nothing for SOCKS, andsocks5://USERNAME:PASSWORD@HOST:PORTfails withnet::ERR_NO_SUPPORTED_PROXIES. - Playwright:
proxy: { server: "socks5://HOST:PORT" }works. AddingusernameorpasswordthrowsBrowser does not support socks5 proxy authenticationat launch, in Chromium and in Firefox.
import puppeteer from "puppeteer";
import { chromium } from "playwright";
// Puppeteer: the scheme goes in the flag. No page.authenticate call.
const pptrBrowser = await puppeteer.launch({
args: ["--proxy-server=socks5://gw-rotating_datacenter.node4.io:1083"],
});
// Playwright: server only. Adding username or password throws at launch.
const pwBrowser = await chromium.launch({
proxy: { server: "socks5://gw-rotating_datacenter.node4.io:1083" },
});That leaves two ways to use a browser with a proxy that needs a login:
- Use the HTTP port. Same account, same username and password, same exits, and for web pages it gives up nothing to SOCKS5. This is the right answer for almost every browser job.
- Whitelist your IP and use SOCKS5 with no login. Register the machine's public address under Auth & IP Access in Account Settings, and the SOCKS5 port accepts it without credentials. With no username there is nowhere to put a country or a session id, so the exit is untargeted. IP whitelisting best practices covers where a whitelist holds up.
A local forwarder such as the proxy-chain package (it listens on localhost without a login and adds the credentials upstream) is a third route when you are tied to a SOCKS5-only provider. With an HTTP port available you do not need it. SOCKS5 proxy setup covers the protocol outside browsers.
Rotating proxies in Puppeteer and Playwright
A browser cannot change its proxy per request, so rotation happens in one of three places:
| Approach | You get a new exit when | Cost | Fits |
|---|---|---|---|
| Rotating gateway, no session | The browser opens a new connection | Nothing to manage, but one page load can leave from several exits | Single stateless page fetches |
| Rotating gateway, one session per context | You open a context with a new session id | A context takes milliseconds to create | Most scraping, and anything with a login |
| One browser per proxy from a static list | You relaunch Chromium | A full browser process per exit | A few fixed addresses that a target has allow-listed |
The middle row is the one to build on. A rotating gateway is one hostname with a pool behind it, and it picks an exit for each connection the browser opens. A page load opens several connections in parallel, so with a bare username the document and its scripts can arrive from different addresses. A session id in the username holds one exit for everything that context does:
import { randomUUID } from "node:crypto";
import { chromium } from "playwright";
const browser = await chromium.launch();
async function scrape(url) {
// A new session id per task: a new exit for this context, held for the task.
const sessionId = randomUUID().replaceAll("-", "").slice(0, 12);
const context = await browser.newContext({
proxy: {
server: "http://gw-rotating_datacenter.node4.io:8083",
username: `USERNAME-session-${sessionId}`,
password: "PASSWORD",
},
});
try {
const page = await context.newPage();
await page.goto(url, { waitUntil: "domcontentloaded" });
return await page.title();
} finally {
await context.close();
}
}
const urls = ["https://example.com/", "https://example.org/", "https://example.net/"];
console.log(await Promise.all(urls.map(scrape)));
await browser.close();In Puppeteer, do the same with createBrowserContext and page.authenticate from the earlier example. A new session id on a second page of the same context will not rotate anything, because Chromium keeps using the first login.
A new session id gets a fresh pick from the pool, which is usually a different address and occasionally the same one. If two workers must not share an exit, compare their exit addresses and re-roll. The worker-pool pattern over a static list, and rotating on evidence of a block instead of on a timer, are worked through in Puppeteer rotating proxy. Selenium has its own credential problem and its own answers in Selenium proxy setup.
Sticky sessions for logins
A login, a cart or a multi-step form needs every request to leave from one address. On Node4 the session is a segment in the username:
USERNAME-session-acct4182 one exit, any country the gateway serves
USERNAME-country-us-session-acct4182 one US exitThe id is any string of letters and digits you choose (up to 32 characters on residential). The same id returns the same exit while the session lasts; nothing has to be created or released.
| Product | How long one session id holds its exit |
|---|---|
| Rotating Datacenter, Rotating Unmetered | Up to 30 minutes from first use. Activity does not extend it |
| Residential | Best effort, up to 30 minutes. It can end early if the device behind the exit goes offline |
| Shared and dedicated datacenter | No session needed: each proxy is one fixed address |
Sessions apply to the gateway products only. Rotating exits are in the US, Italy and Spain, selected with -country-us, -country-it or -country-es; residential adds state, city and ASN segments, set out in residential country and city targeting.
Plan for the session ending. One context per account, one session id per attempt, and a restart from the login step when the target stops recognizing you:
import { chromium } from "playwright";
const browser = await chromium.launch();
async function runAccount(accountId) {
for (let attempt = 1; attempt <= 3; attempt++) {
const context = await browser.newContext({
proxy: {
server: "http://gw-rotating_datacenter.node4.io:8083",
// One session id per account and attempt: every request in this
// context leaves from one exit while the session lasts.
username: `USERNAME-country-us-session-acct${accountId}try${attempt}`,
password: "PASSWORD",
},
});
try {
const page = await context.newPage();
await page.goto("https://example.com/login");
// ...log in, then do the work that depends on the login...
await page.goto("https://example.com/account");
if (page.url().includes("/login")) throw new Error("login lost");
return;
} catch (err) {
if (attempt === 3) throw err; // otherwise: new context, new exit, start over
} finally {
await context.close();
}
}
}
await runAccount(4182);
await browser.close();Work that outlives the window should finish a unit, open a new context with a new id, and log in again. For an identity that must keep one address for days, use a dedicated datacenter proxy and skip sessions entirely. Sticky vs rotating sessions explains what breaks when an exit changes mid-flow.
If your IP is whitelisted, the browser sends no session
A browser sends its proxy login only after the proxy asks for one. A whitelisted address is never asked: the gateway recognizes the source and serves the request, so page.authenticate and Playwright's username are never used, and the country and session segments inside them never arrive. The symptom is an exit that keeps changing although the username has a session id.
To target or pin sessions from a browser, connect from an address that is not on your whitelist, with the username and password. To confirm what the gateway received, run the curl command from the Playwright authentication section with the same username through a rotating gateway and read the X-Node4-Sticky header on the tunnel response: opened or held means a session was applied, none means no session segment arrived.
Check the exit IP from inside the browser
Test from a page, not from your script's own HTTP client. The two can use different proxy settings, and a fetch in Node tells you nothing about what the browser's pages see.
async function exitIp(context) {
const page = await context.newPage();
try {
const response = await page.goto("https://api.ipify.org/");
return (await response.text()).trim();
} finally {
await page.close();
}
}This works with a Puppeteer or a Playwright context. Three results to check:
- It prints your own address. The proxy setting did not apply. Look for a typo in the flag name or a
proxyobject passed to the wrong call. - Two contexts with different sessions print the same address. In Puppeteer, the two pages share a context. Otherwise your source IP is whitelisted (previous section), or the pool happened to pick the same exit twice.
- One context prints a different address on each call. The username has no session segment, or the session has expired.
WebRTC and DNS leaks
A proxy setting covers HTTP traffic. Two browser features need a look.
WebRTC. WebRTC finds network routes by sending UDP to STUN servers, and UDP does not go through an HTTP proxy. A page's JavaScript can read your real address that way. One Chromium flag stops it:
import puppeteer from "puppeteer";
import { chromium } from "playwright";
const leakFlags = [
"--force-webrtc-ip-handling-policy=disable_non_proxied_udp",
];
// Puppeteer
const pptrBrowser = await puppeteer.launch({
args: ["--proxy-server=http://HOST:PORT", ...leakFlags],
});
// Playwright (Chromium)
const pwBrowser = await chromium.launch({
proxy: { server: "http://HOST:PORT", username: "USERNAME", password: "PASSWORD" },
args: leakFlags,
});Pages that depend on WebRTC, such as video calls, degrade or fail with the policy set. Confirm it by loading a public WebRTC leak test in the proxied browser: the only address shown should be the proxy exit.
DNS. With an http:// proxy the browser sends the hostname to the proxy inside the CONNECT request, and the proxy resolves it. Navigations do not touch your resolver. With socks5://, Chromium and Firefox also hand the hostname to the proxy; there is no socks5h:// variant to remember as there is in curl or Python. Two things can still resolve locally:
- Hosts on a bypass list (
--proxy-bypass-list, or Playwright'sbypass). Keep that list to local addresses. - Chromium's background DNS prefetching when a SOCKS proxy is in use. Chromium's own SOCKS notes pair the proxy flag with
--host-resolver-rules="MAP * ~NOTFOUND , EXCLUDE HOST"(your proxy hostname in place ofHOST) to block those lookups.
Closing both does not disguise the browser itself. Its timezone, language and fingerprint are separate signals, and a German exit with a US locale stands out. Playwright sets locale and timezoneId per context so they can match the exit country.
Cut the bandwidth of a page load
A headless page load downloads the document plus every script, font, image and tracker it references, so it moves several times the bytes of the same URL fetched with an HTTP client. On a per-gigabyte plan, drop what you do not need:
const SKIP = new Set(["image", "media", "font"]);
async function blockPuppeteer(page) {
await page.setRequestInterception(true);
page.on("request", (request) => {
if (SKIP.has(request.resourceType())) request.abort();
else request.continue();
});
}
async function blockPlaywright(context) {
await context.route("**/*", (route) => {
if (SKIP.has(route.request().resourceType())) return route.abort();
return route.continue();
});
}Check the target still behaves the same with images blocked before relying on it. If page weight is what drives your bill, Rotating Unmetered is priced by concurrent connections instead of bytes ($29.00/month for 250 connections ($0.116 per connection), on unmetered pricing). A browser holds several connections per page, so size the plan from the peak you observe; Rotating Unmetered connection limits shows how to measure it.
Common Puppeteer and Playwright proxy errors
| What you see | What it means | Fix |
|---|---|---|
net::ERR_PROXY_CONNECTION_FAILED (Firefox: NS_ERROR_PROXY_CONNECTION_REFUSED) | The browser could not open a connection to the proxy at all | Check host and port for typos, that the port belongs to the product you bought, and that your network allows outbound traffic to it. Connection issues walks the layers |
net::ERR_TUNNEL_CONNECTION_FAILED (Firefox: NS_ERROR_PROXY_BAD_GATEWAY) | The proxy was reached and logged you in, then refused to open the tunnel. Chromium hides the status code | Run the curl command above with the same username. On Node4, 502 means the requested country has no exits or the exit could not reach the site, 429 means a Rotating Unmetered plan is at its connection limit, and 503 on a rotating gateway means a session could not be pinned right now |
net::ERR_INVALID_AUTH_CREDENTIALS | Puppeteer: the proxy asked for a login and none was supplied | Call page.authenticate before the first goto |
Response status 407 | The login was sent and refused: wrong password, or a product your account has no plan for | Test with curl, then follow the 407 guide. A free account gets a 407 from the rotating and residential gateways |
page.goto: Timeout 30000ms exceeded on the first page | Playwright on Chromium with wrong or missing credentials, HTTPS target | Same as 407 |
net::ERR_NO_SUPPORTED_PROXIES | Credentials inside --proxy-server, or a malformed value | Address in the flag, login in page.authenticate |
Browser does not support socks5 proxy authentication | Playwright with socks5:// plus username or password | Use the HTTP port, or whitelist your IP and remove the login |
net::ERR_SOCKS_CONNECTION_FAILED | The SOCKS5 proxy refused the connection, commonly because the source IP is not whitelisted | Whitelist the address the traffic leaves from, or switch to the HTTP port |
| The site loads but shows a block page or a CAPTCHA | The proxy works. The target refused the exit or the browser fingerprint | Try a session on another exit, then a different proxy type. See why is my IP getting blocked |
| The exit IP changes on every request | No session segment reached the gateway | See the whitelist section above, and check the spelling of -session- |
A misspelled segment does not always produce an error. On the rotating gateways USERNAME-sesion-x is treated as a different username and refused with a 407, while a typo after a valid segment can be read as part of that segment's value. Write the order USERNAME-country-xx-session-ID and check the exit after any change.
Which Node4 proxy to point the browser at
The setup above is identical for every product; only the host, port and username change.
- Target accepts datacenter addresses: Rotating Datacenter, billed per gigabyte ($5.90/month for 10 GB ($0.59/GB), see rotating pricing).
- Heavy pages or many workers: Rotating Unmetered, the same pool priced by concurrent connections.
- Target refuses datacenter ranges: residential proxies, with country, state and city targeting ($4.99/month for 3 GB ($1.66/GB), see residential pricing).
- One identity on one address for days: a dedicated datacenter proxy.
Test your real target on the smallest plan before scaling: a proxy changes the address a site sees, not the browser fingerprint. The full comparison for headless browsers, including what a page load does to each billing unit, is on proxies for Puppeteer, Playwright and Selenium.
Runnable Puppeteer and Playwright scripts are in the Node.js folder of our examples repository on GitHub.