How to set up a proxy in Puppeteer

What you need

The proxy is issued in the format host:port:login:password. Replace HOST, PORT, LOGIN and PASSWORD with your own values. Puppeteer downloads a suitable Chrome when installed.

npm install puppeteer

Chrome does not accept a login and password inside the value of the --proxy-server flag, so the proxy address is set with the flag and the credentials are passed with the page.authenticate method, which answers the authentication challenge.

Example

import puppeteer from "puppeteer";

const browser = await puppeteer.launch({
  // The proxy address without a login and password. The http:// scheme even for HTTPS sites
  args: ["--proxy-server=http://HOST:PORT"],
});

const page = await browser.newPage();

// The login and password are separate from the address, no need to encode them.
// It must be called before page.goto
await page.authenticate({ username: "LOGIN", password: "PASSWORD" });

// Page navigation timeout in milliseconds
await page.goto("https://api.ipify.org", { timeout: 30000 });

// The service returns the address the request came from
console.log(await page.evaluate(() => document.body.innerText));

await browser.close();

If SOCKS5

The --proxy-server flag also accepts the socks5://HOST:SOCKS_PORT scheme, but we could not confirm from the documentation a way to pass a SOCKS5 login and password in Chrome: page.authenticate is designed for HTTP authentication. For a proxy with a login and password, use the HTTP port.

Common errors

1. The page shows ERR_INVALID_AUTH_CREDENTIALS or 407: the login or password is wrong, or page.authenticate was called after page.goto.
2. ERR_PROXY_CONNECTION_FAILED or a navigation timeout: check HOST and PORT, whether the SOCKS5 port was put into HTTP mode, and increase the goto timeout.
3. Special characters in the password: through page.authenticate the password is passed as is. Do not put the login and password into --proxy-server: Chrome does not use them there.
4. The https:// scheme in --proxy-server: the issued proxy works over HTTP, so write http://HOST:PORT or simply HOST:PORT.
5. A single page.authenticate applies to a specific page; for a new tab, call it again.