Playwright

Proxies for Playwright let the browser connect through a different IP address instead of always using the IP of the machine running it. This is useful for location-based tasks, testing, monitoring, and other jobs where the connection source matters.

Playwright still controls the browser and its requests. The proxy handles where the connection comes from.

What happens without one: IP bans, rate limits, geo walls

Without a proxy, websites keep seeing the same IP. As activity increases, that IP may hit a rate limit or get blocked.

Location can matter too. A page opened from Germany may not return the same content as one opened from the US.

A proxy for Playwright makes it possible to connect from different IPs and locations when needed.

Which proxy type to use with Playwright

The right proxy type depends on the job.

Residential proxies are useful when the IP source and location matter. ISP proxies work well when the same IP needs to stay active for longer. Datacenter proxies make sense when the main focus is speed and scale.

The best option also depends on whether the task needs geo-targeting, a stable connection, or access to a larger pool of IPs.

How to connect a proxy in Playwright

The Playwright proxy setup needs the Geonode host, port, username, and password. Keep the credentials in environment variables, then pass them through Playwright's proxy option when launching Chromium.

Using Geonode? Get the username and password from Access Credentials and the host, port, and protocol from Proxy Server Information.

Settings path or code

Configure the proxy when launching the browser:

import { chromium } from "playwright";
import "dotenv/config";

const browser = await chromium.launch({
  headless: true,
  proxy: {
    server: `http://${process.env.GEONODE_PROXY_HOST}:${process.env.GEONODE_PROXY_PORT}`,
    username: process.env.GEONODE_PROXY_USER,
    password: process.env.GEONODE_PROXY_PASS,
  },
});

Playwright accepts the proxy through chromium.launch() or a browser context. The launch configuration was used in our test.

Then create a page and make the request:

const page = await browser.newPage();

const response = await page.goto("http://ip-api.com/json", {
  waitUntil: "domcontentloaded",
  timeout: 45000,
});

console.log(response.status());
console.log(await page.locator("body").innerText());

await browser.close();

The basic test returned HTTP 200 and proxy IP 172.56.18.51, confirming that the request was going through the proxy.

Authentication format host:port:user:pass

Geonode gives you four values:

proxy.geonode.io:PORT:USERNAME:PASSWORD

Store them in environment variables instead of putting the credentials directly in the source file:

GEONODE_PROXY_HOST=proxy.geonode.io
GEONODE_PROXY_PORT=9000
GEONODE_PROXY_USER=YOUR_USERNAME
GEONODE_PROXY_PASS=YOUR_PASSWORD

Then pass the username and password through Playwright's proxy configuration:

const browser = await chromium.launch({
  proxy: {
    server: `http://${process.env.GEONODE_PROXY_HOST}:${process.env.GEONODE_PROXY_PORT}`,
    username: process.env.GEONODE_PROXY_USER,
    password: process.env.GEONODE_PROXY_PASS,
  },
});

Playwright expects authenticated proxy credentials in proxy.username and proxy.password. With valid credentials, our authentication test returned HTTP 200.

Rotation vs sticky session in Playwright

If the requests do not need to keep the same IP, use rotation.

Configure Playwright with the Geonode rotating proxy:

const browser = await chromium.launch({
  proxy: {
    server: "http://proxy.geonode.io:9000",
    username: process.env.GEONODE_PROXY_USER,
    password: process.env.GEONODE_PROXY_PASS,
  },
});

We opened a fresh browser for each request and recorded the returned IPs:

All five requests returned different IPs in this test, giving us five unique IPs.

If related requests need to stay on the same IP, use a sticky session instead:

const browser = await chromium.launch({
  proxy: {
    server: "http://proxy.geonode.io:10000",
    username: `${process.env.GEONODE_PROXY_USER}-session-blogplaywright01-lifetime-10`,
    password: process.env.GEONODE_PROXY_PASS,
  },
});

The same session returned 178.13.74.93 for all three requests, confirming that the sticky session kept the same IP during the test.

See the Geonode guides for rotating proxies and sticky sessions for the available settings.

Common proxy errors in Playwright and how to fix them

If the proxy is not working, start with the connection details. Check the username and password, then the host, port, and protocol. Playwright's error can usually help narrow down the problem.

407 Proxy Authentication Required

A 407 usually points to an authentication problem.

Our test with incorrect credentials returned:

HTTP 407
Authentication error. Please check your authentication settings.

The same setup worked after the correct username and password were passed through proxy.username and proxy.password.

ERR_TUNNEL_CONNECTION_FAILED / connection refused

A connection error usually means Playwright could not reach the proxy.

Using an unreachable proxy port produced:

page.goto: net::ERR_PROXY_CONNECTION_FAILED

Check the host and port first. Then make sure the protocol matches the proxy server being used.

Timeouts and empty responses

A timeout means the page did not load within the configured time.

When we tested a non-routable proxy with a 5000 ms timeout, Playwright returned:

TimeoutError: page.goto: Timeout 5000ms exceeded.

Set an appropriate timeout on page.goto() so a stalled proxy connection does not leave the request waiting indefinitely.

One error specific to Playwright

Playwright proxy authentication must be configured through the proxy option.

Setting only the proxy server without username and password returned HTTP 407. Trying Puppeteer's page.authenticate() approach does not work either because that API is not available on a Playwright Page.

Use:

const browser = await chromium.launch({
  proxy: {
    server: "http://proxy.geonode.io:9000",
    username: process.env.GEONODE_PROXY_USER,
    password: process.env.GEONODE_PROXY_PASS,
  },
});

After the credentials were moved into the Playwright proxy configuration, the same test returned HTTP 200.

Playwright + Geonode: what you get

Playwright handles browser automation and page requests. Geonode handles the proxy connection.

You can choose residential, ISP, or datacenter proxies based on the job, then use rotation, sticky sessions, and geo-targeting where needed. This keeps the proxy configuration separate from the rest of the browser automation code.

Plans vary by proxy type, with some options priced per GB.

FAQ

If you encounter any issues, refer to the troubleshooting section or Geonode support.