Puppeteer proxy setup: Connecting via --proxy-server & page.authenticate

How do proxies work in Puppeteer?

Puppeteer configures proxies via Chrome launch arguments. --proxy-server sets one proxy for all browser pages. HTTP proxy credentials require page.authenticate since they can't be passed as arguments.

The example uses IP 198.51.100.23, HTTP port 8000, SOCKS5 port 1080, username spx_user, and password spx_pass.

npm install puppeteer

How to connect HTTP proxy with authentication?

Add --proxy-server=198.51.100.23:8000 to launch args, and pass username and password to page.authenticate right after creating a page with newPage. Authentication is required per page, so make the same call each time you create a new page.

HTTPS sites open normally. Browser establishes CONNECT tunnel for encrypted communication within.

import puppeteer from "puppeteer";

const browser = await puppeteer.launch({
  headless: true,
  args: ["--proxy-server=http://198.51.100.23:8000"],
});

const page = await browser.newPage();
await page.authenticate({ username: "spx_user", password: "spx_pass" });

await page.goto("https://api.ipify.org", { waitUntil: "domcontentloaded" });
console.log(await page.evaluate(() => document.body.innerText)); // proxy IP

await browser.close();

How do I use SOCKS5 proxies?

Use socks5:// address in --proxy-server. Note: Chrome doesn't support SOCKS proxy authentication, so page.authenticate won't work with SOCKS5. For SOCKS5 connections, use IP authorization by registering your server's IPv4 in the dashboard.

If you must connect with a username and password, using the HTTP port of the same IP is the simplest solution. The IP remains the same, so the location seen by the target site is unchanged.

import puppeteer from "puppeteer";

const browser = await puppeteer.launch({
  args: ["--proxy-server=socks5://198.51.100.23:1080"], // server IP is authorized in the dashboard
});
const page = await browser.newPage();
await page.goto("https://api.ipify.org");
console.log(await page.evaluate(() => document.body.innerText));
await browser.close();

How do I launch multiple browsers with different IPs?

Chrome only supports one proxy per browser instance. To use different IPs, launch separate browser instances. This code fetches an ip:port:user:pass list via API, launches 3 browsers with different proxies, and displays each page's visible IP.

Multiple browser instances consume significant memory. Implement work queues with concurrency limits.

import puppeteer from "puppeteer";

const KEY = "YOUR_API_KEY";
const res = await fetch("https://socks5proxy.io/api/v1/proxies/download?format=ip:port:user:pass&protocol=http", {
  headers: { Authorization: "Bearer " + KEY },
});
const lines = (await res.text()).trim().split("\n").slice(0, 3);

await Promise.all(lines.map(async (line) => {
  const [ip, port, user, pass] = line.trim().split(":");
  const browser = await puppeteer.launch({ args: ["--proxy-server=http://" + ip + ":" + port] });
  try {
    const page = await browser.newPage();
    await page.authenticate({ username: user, password: pass });
    await page.goto("https://api.ipify.org", { timeout: 30000 });
    console.log(ip, await page.evaluate(() => document.body.innerText));
  } finally {
    await browser.close();
  }
}));

How can I open pages faster?

Proxying images/fonts/videos consumes extra bandwidth. For text-only scraping, use page.setRequestInterception to block media requests - speeding up tasks and conserving shared plan bandwidth.

waitUntil value is also important. networkidle0 waits for all requests to complete, which can be slow. Use page.waitForSelector to proceed as soon as the required element is visible.

await page.setRequestInterception(true);
page.on("request", (req) => {
  const type = req.resourceType();
  if (type === "image" || type === "font" || type === "media") req.abort();
  else req.continue();
});

Can I use different IPs per page in one browser?

Chrome's --proxy-server applies globally, making per-page IP switching difficult. Puppeteer 22+ supports proxyServer in browser.createBrowserContext for context-specific proxies. Contexts have isolated cookies/storage, ideal for account-specific tasks.

Use page.authenticate to pass credentials for pages created in context - more memory-efficient than multiple browser instances.

import puppeteer from "puppeteer";

const browser = await puppeteer.launch();
const context = await browser.createBrowserContext({ proxyServer: "http://198.51.100.23:8000" });
const page = await context.newPage();
await page.authenticate({ username: "spx_user", password: "spx_pass" });
await page.goto("https://api.ipify.org");
console.log(await page.evaluate(() => document.body.innerText));
await context.close();
await browser.close();

What settings make me appear as a user from that country?

Configure Accept-Language via page.setExtraHTTPHeaders and timezone via page.emulateTimezone to match your proxy's country. Mismatches may display incorrect languages or date formats.

Set viewport size with page.setViewport. For mobile emulation, pass Puppeteer’s KnownDevices presets to page.emulate.

await page.setExtraHTTPHeaders({ "Accept-Language": "ja-JP,ja;q=0.9" });
await page.emulateTimezone("Asia/Tokyo");
await page.setViewport({ width: 1366, height: 900 });

How to keep browsers stable during long-running tasks?

For 24/7 operations, periodically restarting browsers after processing certain page counts is more stable than keeping them open continuously. Long-running browsers consume increasing memory and risk halting all subsequent operations if errors occur.

Always call page.close in try and finally blocks, and add a timeout to goto to avoid getting stuck on unresponsive pages. Retry failed tasks by launching a new browser with a different proxy.

Logging proxy response times and errors per proxy helps identify slow connections - useful when contacting support or adjusting task batches.

How do I resolve frequent errors?

net::ERR_INVALID_AUTH_CREDENTIALS or 407 occurs when page.authenticate values are incorrect or not called after newPage. Verify that it’s called before goto for each page.

net::ERR_PROXY_CONNECTION_FAILED occurs when the address or port is incorrect. Ensure you’re using the HTTP port for HTTP addresses and the SOCKS5 port for SOCKS5 addresses. If SOCKS5 connection is rejected, verify that the outgoing IP is registered for IP authorization.