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.

PuppeteerPlaywright
Proxy addressargs: ["--proxy-server=http://HOST:PORT"]proxy: { server: "http://HOST:PORT" }
Username and passwordpage.authenticate({ username, password })username and password in the same proxy object
A different proxy per contextbrowser.createBrowserContext({ proxyServer })browser.newContext({ proxy })
A different proxy per pageNo. Use one context per proxyNo. Use one context per proxy
SOCKS5 with a loginNot supported by ChromiumRefused at launch
Python APINonesync_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, or npm install playwright followed by npx playwright install chromium. For Python: pip install playwright, then playwright 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.47

With 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 with net::ERR_INVALID_AUTH_CREDENTIALS.
  • A wrong password does not throw. goto resolves normally with a response whose status() is 407. 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.authenticate on 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 wantWriteNotes
To load https:// sites through a proxyhttp://HOST:PORTThe 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:// siteshttp://HOST:PORTSame setting
SOCKS5socks5://HOST:PORTNo 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:PORT works. page.authenticate does nothing for SOCKS, and socks5://USERNAME:PASSWORD@HOST:PORT fails with net::ERR_NO_SUPPORTED_PROXIES.
  • Playwright: proxy: { server: "socks5://HOST:PORT" } works. Adding username or password throws Browser does not support socks5 proxy authentication at 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:

  1. 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.
  2. 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:

ApproachYou get a new exit whenCostFits
Rotating gateway, no sessionThe browser opens a new connectionNothing to manage, but one page load can leave from several exitsSingle stateless page fetches
Rotating gateway, one session per contextYou open a context with a new session idA context takes milliseconds to createMost scraping, and anything with a login
One browser per proxy from a static listYou relaunch ChromiumA full browser process per exitA 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 exit

The 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.

ProductHow long one session id holds its exit
Rotating Datacenter, Rotating UnmeteredUp to 30 minutes from first use. Activity does not extend it
ResidentialBest effort, up to 30 minutes. It can end early if the device behind the exit goes offline
Shared and dedicated datacenterNo 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 proxy object 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's bypass). 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 of HOST) 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 seeWhat it meansFix
net::ERR_PROXY_CONNECTION_FAILED (Firefox: NS_ERROR_PROXY_CONNECTION_REFUSED)The browser could not open a connection to the proxy at allCheck 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 codeRun 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_CREDENTIALSPuppeteer: the proxy asked for a login and none was suppliedCall page.authenticate before the first goto
Response status 407The login was sent and refused: wrong password, or a product your account has no plan forTest 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 pagePlaywright on Chromium with wrong or missing credentials, HTTPS targetSame as 407
net::ERR_NO_SUPPORTED_PROXIESCredentials inside --proxy-server, or a malformed valueAddress in the flag, login in page.authenticate
Browser does not support socks5 proxy authenticationPlaywright with socks5:// plus username or passwordUse the HTTP port, or whitelist your IP and remove the login
net::ERR_SOCKS_CONNECTION_FAILEDThe SOCKS5 proxy refused the connection, commonly because the source IP is not whitelistedWhitelist the address the traffic leaves from, or switch to the HTTP port
The site loads but shows a block page or a CAPTCHAThe proxy works. The target refused the exit or the browser fingerprintTry a session on another exit, then a different proxy type. See why is my IP getting blocked
The exit IP changes on every requestNo session segment reached the gatewaySee 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.