Puppeteer Proxy: How to Use Authenticated Proxies in Puppeteer

Developer guide · Last reviewed 27 September 2026 · 10 min read

A Puppeteer proxy takes two things: the proxy address, which Chrome gets as a launch flag, and the username and password, which Puppeteer answers when the proxy asks. This guide shows the working setup with --proxy-server and page.authenticate(), how to give each browser context its own proxy, how to rotate IPs or keep sticky sessions with rotating residential proxies, and how to fix the errors people hit most often.

How Puppeteer Uses a Proxy

Puppeteer drives a real Chrome or Chromium browser, and it’s the browser, not your Node.js code, that opens the network connections. So the proxy has to be given to the browser. There are two places to do it: the --proxy-server command-line flag when you launch Chrome, which applies to the whole browser, or the proxyServer option when you create a browser context, which applies to that context only.

Authentication is a separate step. When Chrome connects to a proxy that needs a login, the proxy replies with 407 Proxy Authentication Required, and the browser has to answer with credentials. In a normal Chrome window that would be a sign-in box. In Puppeteer, page.authenticate() supplies the username and password so the page can load without anyone typing them.

puppeteer.launch({ args: ['--proxy-server=http://HOST:PORT'] })
        |
        v
   Chrome  ----- CONNECT ---->  proxy (asks for a login: 407)
        ^                            |
        |                            v
page.authenticate({ username, password })  -->  target website

The Puppeteer documentation describes page.authenticate() simply as providing credentials for HTTP authentication, and notes that request interception is turned on behind the scenes to do it, which can affect performance. For most scraping and testing jobs that cost is small.

Puppeteer Proxy with Authentication: the Standard Setup

This is the setup that works for almost everyone. Get your host, port, username and password from the Proxy Manager in your ProxyEmpire dashboard, then:

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  args: ['--proxy-server=http://v2.proxyempire.io:5000'],
});

const page = await browser.newPage();

// Answer the proxy's login request for this page
await page.authenticate({
  username: process.env.PROXY_USER,
  password: process.env.PROXY_PASS,
});

await page.goto('https://api.ipify.org?format=json');
console.log(await page.evaluate(() => document.body.innerText));

await browser.close();

A few details that save time:

• Call page.authenticate() on every page, before its first goto(). A new tab opened with browser.newPage() needs its own call.
• Keep credentials out of your code. Read them from environment variables or a secrets manager. Anyone with your proxy username and password can spend your bandwidth.
• Use the IP check to confirm it works. The response should show an address and location from the proxy, not your own connection.
• Your username encodes your targeting. With ProxyEmpire, the username changes when you change country, city or session settings, so copy it again from the dashboard after any change.

Putting the credentials in the URL, as in --proxy-server=http://user:pass@host:port, is the most common mistake. Chrome doesn’t accept credentials in that flag, so the proxy keeps returning a 407 and pages fail to load.

A Different Proxy for Each Browser Context

Launching a new browser for every proxy is slow. Puppeteer’s browser.createBrowserContext() creates an isolated context that doesn’t share cookies or cache with other contexts, and its proxyServer option gives that context its own proxy. The Puppeteer docs note that the username and password for it are set with page.authenticate(), the same as before.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();

async function openWithProxy(username) {
  const context = await browser.createBrowserContext({
    proxyServer: 'http://v2.proxyempire.io:5000',
  });
  const page = await context.newPage();
  await page.authenticate({ username, password: process.env.PROXY_PASS });
  return { context, page };
}

const a = await openWithProxy(process.env.PROXY_USER_US);
const b = await openWithProxy(process.env.PROXY_USER_DE);

await a.page.goto('https://example.com');
await b.page.goto('https://example.com');

await a.context.close();
await b.context.close();
await browser.close();

Because the ProxyEmpire username carries the targeting and session settings, two contexts with two usernames can browse from two different countries, or two different sticky IPs, in the same browser. createBrowserContext() is the current name for what older Puppeteer versions called createIncognitoBrowserContext(). If you are on an old version, upgrade or use the older name.

The proxy-chain Alternative

Some setups can’t call page.authenticate(): service workers and some pop-ups, tools that wrap Puppeteer, or code that needs to pass one proxy URL to Chrome and forget about it. The open-source proxy-chain package solves this. Its anonymizeProxy() function starts a small local proxy with no password that forwards everything to your authenticated proxy, so Chrome only ever sees a local address.

import puppeteer from 'puppeteer';
import { anonymizeProxy, closeAnonymizedProxy } from 'proxy-chain';

const upstream = `http://${process.env.PROXY_USER}:${process.env.PROXY_PASS}@v2.proxyempire.io:5000`;
const localProxy = await anonymizeProxy(upstream);   // e.g. http://127.0.0.1:12345

const browser = await puppeteer.launch({ args: [`--proxy-server=${localProxy}`] });
const page = await browser.newPage();                 // no page.authenticate() needed
await page.goto('https://api.ipify.org?format=json');

await browser.close();
await closeAnonymizedProxy(localProxy, true);

If your password contains characters such as @, : or /, URL-encode it before building the upstream URL. Remember to close the local proxy when you’re done, or it keeps running in your process.

Rotating IPs and Sticky Sessions in Puppeteer

With a rotating proxy endpoint, you choose the behaviour in the dashboard rather than in your code:

For a browser, sticky sessions are usually the right default. A single page load pulls in scripts, images and API calls, and if those come from different IPs, some sites treat the visit as suspicious. Use one sticky session per browser context, and switch to a new session, by using a new username from the dashboard, when you want a fresh identity.

Running many sessions in parallel

Scraping jobs often run dozens of pages at once. The pattern that scales is one browser, many contexts: each context gets its own proxy username and its own cookies, and a small pool of contexts works through a queue of URLs. ProxyEmpire has no limit on concurrent sessions, so the practical limit is your machine’s memory and CPU, not the proxy. Keep an eye on both, since every Chrome context and tab uses real resources.

Give each worker a clear lifecycle: create the context, authenticate its pages, process a batch of URLs, then close the context and start a fresh one with a new session. Recycling contexts regularly keeps memory in check and gives you a new IP at predictable points instead of in the middle of a job.

Checking that the proxy is really used

Before a long run, load an IP-check page in each context and log the result, as in the first example. If a context prints your own address, its proxy wasn’t applied; if it prints nothing, the login probably failed. A second quick check is to confirm the country matches the targeting you chose, since a working proxy in the wrong location still ruins location-specific data.

SOCKS5 and Puppeteer

Chrome accepts SOCKS proxies in --proxy-server, but it has no way to send a username and password to a SOCKS5 proxy. The feature request for SOCKS5 authentication in the Chromium issue tracker is closed without being implemented. If you pass an authenticated SOCKS5 proxy to Puppeteer, requests fail or the credentials are dropped.

The fix is simple: use the HTTP endpoint. ProxyEmpire supports HTTP, HTTPS and SOCKS5 on the same account, and HTTP with page.authenticate() still carries HTTPS traffic through an encrypted tunnel to the target site. If you really need SOCKS5 in the browser, proxy-chain can sit in the middle so Chrome talks to a local proxy without a password.

Troubleshooting Puppeteer Proxy Errors

If none of these fit, the proxy troubleshooting guide in our docs covers the rest, and the 24/7 live chat is answered by real people who can look at your setup with you.

Which Proxies to Use with Puppeteer

Puppeteer is often used on the sites that are hardest to reach, the ones that need JavaScript and check visitors closely. That makes the IP type matter.

• Rotating residential proxies come from real home broadband connections in 179 countries and territories, with targeting down to city, ZIP, ISP and ASN. They are the default choice for browser automation, from $3.50 for one GB down to $1.50/GB.
• Rotating mobile proxies use 4G carrier networks in 174 countries, from $2.00/GB. Use them for mobile sites, app back ends and anything that treats phones differently.
• Datacenter proxies are cheapest, from $0.35/GB, and fine for sites without strong bot checks.

All three work with the setup in this guide, and unused bandwidth rolls over on every plan. For more on running browsers at scale, see our guide to web automation with Chromium.

Puppeteer Proxy FAQ

References

1. Puppeteer — Page.authenticate(). pptr.dev/api/puppeteer.page.authenticate
2. Puppeteer — Browser.createBrowserContext(). pptr.dev/api/puppeteer.browser.createbrowsercontext
3. Puppeteer — BrowserContextOptions (proxyServer, proxyBypassList). pptr.dev/api/puppeteer.browsercontextoptions
4. Chromium — Network settings (the --proxy-server flag). chromium.org/developers/design-documents/network-settings
5. Chromium issue tracker — SOCKS5 authentication support. issues.chromium.org/issues/40323993
6. Apify — proxy-chain (anonymizeProxy, closeAnonymizedProxy). github.com/apify/proxy-chain
7. MDN — 407 Proxy Authentication Required. developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Status/407