How to use an authenticated proxy with Puppeteer

Your proxy details

After you buy a plan, open My proxies. Choose the Proxy Type (Rotating or Sticky), the Protocol (HTTP or SOCKS5) and a Format, then copy a line. The generator offers three formats:

In the examples on this page, replace USERNAME, PASSWORD, HOST and PORT with the values from your line. SOCKS5_PORT is the port the generator shows when you pick SOCKS5.

Residential lines are either rotating (a new IP on new connections) or sticky (one IP for the time you choose). Datacenter and ISP plans give you a list of dedicated IPs, one per line as IP:PORT:USERNAME:PASSWORD, and each line is one fixed IP.

To test a line, open https://ipinfo.io/json through it: it shows the exit IP and country. For HTTP lines you can also use the free proxy checker.

Launch with a proxy and log in

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' });

await page.goto('https://ipinfo.io/json');
console.log(await page.evaluate(() => document.body.innerText));

await browser.close();

Keep the username and password out of --proxy-server. Chrome ignores credentials in that flag, which is why page.authenticate() exists.

Call page.authenticate() on every new page before its first goto(), including pages opened from a popup or a new tab.

A different proxy for each browser context

Browser contexts are isolated, like separate incognito windows, and each can have its own proxy. This lets one browser run several sessions with different IPs.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch();

// Two sticky lines from the generator: same host and port, different usernames.
const lines = [
  { username: 'STICKY_USERNAME_1', password: 'PASSWORD' },
  { username: 'STICKY_USERNAME_2', password: 'PASSWORD' },
];

for (const credentials of lines) {
  const context = await browser.createBrowserContext({ proxyServer: 'http://HOST:PORT' });
  const page = await context.newPage();
  await page.authenticate(credentials);
  await page.goto('https://ipinfo.io/json');
  console.log(await page.evaluate(() => document.body.innerText));
  await context.close();
}

await browser.close();

In Puppeteer versions before 22, the method is called createIncognitoBrowserContext().

Sticky sessions

Use sticky lines in browsers. A browser opens many connections for one page, so with a rotating line a single page load can come from several IPs, which breaks logins and looks unnatural. To make sticky lines, open the generator, set Proxy Type to Sticky, choose a Sticky Duration if your plan offers one, set how many lines you want in Sticky Amount, then copy or download them. Each line keeps its IP for the chosen time. The session part of a sticky username differs by plan, so always generate sticky lines instead of editing usernames by hand.

Target a country

On residential plans, add -country- and a two-letter country code to the end of the username, for example USERNAME-country-us or USERNAME-country-gb. To combine a country with a state, a city or a sticky session, build the line in the generator, which shows only the options your plan supports. Datacenter and ISP IPs have a fixed location that you choose when you buy them. In Puppeteer, the country tag goes in the username you pass to page.authenticate().

await page.authenticate({ username: 'USERNAME-country-us', password: 'PASSWORD' });

SOCKS5

Chrome doesn’t support usernames and passwords for SOCKS5 proxies, so use HTTP lines with Puppeteer. SOCKS5 works only without a password, which needs your IP on the Access & API allow-list on a plan that supports login by IP. Then launch with --proxy-server=socks5://HOST:SOCKS5_PORT.

Use less data

Residential plans bill by the gigabyte, and images, fonts and video are most of a page’s weight. Skip them when you only need the HTML.

await page.setRequestInterception(true);
page.on('request', (req) => {
  if (['image', 'media', 'font'].includes(req.resourceType())) req.abort();
  else req.continue();
});

Troubleshooting

• net::ERR_TUNNEL_CONNECTION_FAILED

  The proxy refused the CONNECT request. Run the line through curl -v to see the real status (407, 502 or 503).More on this error →

• net::ERR_PROXY_CONNECTION_FAILED

  The browser couldn’t reach the proxy at all. Check the host and port, and that you used the HTTP port for an http:// proxy.More on this error →

• A 407 page, or net::ERR_INVALID_AUTH_CREDENTIALS

  The page has no credentials or the wrong ones. Call page.authenticate() on that page before goto(), and check the line.More on this error →

• Different IPs within one page load

  You’re using a rotating line in a browser. Switch to a sticky line.More on this error →

Seeing another error? Read proxy errors and how to fix them, or contact support.

Questions