How to Use Proxies with Puppeteer

Set a browser-wide proxy at launch

The launch argument supplies the proxy server to Chrome. Keep the value separate from credentials and validate it before passing it into the browser.

import puppeteer from 'puppeteer';

const proxyServer = process.env.PROXY_SERVER;
if (!proxyServer) throw new Error('PROXY_SERVER is required');

const browser = await puppeteer.launch({
  headless: true,
  args: [
    `--proxy-server=${proxyServer}`,
    '--proxy-bypass-list=localhost;127.0.0.1'
  ]
});

try {
  const page = await browser.newPage();

  if (process.env.PROXY_USERNAME) {
    await page.authenticate({
      username: process.env.PROXY_USERNAME,
      password: process.env.PROXY_PASSWORD || ''
    });
  }

  await page.goto('https://api.ipify.org?format=json', {
    waitUntil: 'domcontentloaded',
    timeout: 30_000
  });

  console.log(await page.evaluate(() => document.body.innerText));
} finally {
  await browser.close();
}

The official Page.authenticate documentation notes that request interception is enabled behind the scenes and can affect performance. Authenticate before navigation and measure the result rather than hiding timing changes with a very large timeout.

Do not embed username:password in the launch argument. It can appear in process lists, CI diagnostics or crash reports. Use environment variables or a secret manager and mask any error message that includes configuration.

Configure a proxy for an isolated browser context

Recent Puppeteer APIs include proxyServer and proxyBypassList in browser context options. This is useful when separate contexts need different exits while sharing one browser process. Check the Puppeteer version in your project because older versions may require a launch-level proxy or a different design.

const context = await browser.createBrowserContext({
  proxyServer: process.env.PROXY_SERVER,
  proxyBypassList: ['localhost', '127.0.0.1']
});

const page = await context.newPage();

if (process.env.PROXY_USERNAME) {
  await page.authenticate({
    username: process.env.PROXY_USERNAME,
    password: process.env.PROXY_PASSWORD || ''
  });
}

await page.goto('https://example.com');
await context.close();

The official BrowserContextOptions reference documents the proxy server option and points to Page.authenticate for username/password. Keep one stateful journey inside one context and do not swap the route while cookies or account state are active.

Verify the proxy before the real page

An IP endpoint gives a cheap routing check, but production acceptance should verify four things: the observed IP matches the assigned endpoint or expected pool, location fits the scenario, the real target loads, and required content is present. Store those results with a masked proxy identifier.

const response = await page.goto(
  'https://api.ipify.org?format=json',
  { waitUntil: 'domcontentloaded', timeout: 30_000 }
);

if (!response || !response.ok()) {
  throw new Error(`IP check failed: ${response?.status()}`);
}

const { ip } = JSON.parse(
  await page.evaluate(() => document.body.innerText)
);

if (!ip) throw new Error('No proxy exit IP returned');

Use the proxy tester before browser automation when the endpoint itself is uncertain. This separates a dead proxy from a Puppeteer configuration or page assertion problem.

Proxy assignment for pages, contexts and workers

All pages in a launch-level browser normally share the same proxy. If each worker needs a different endpoint, use supported per-context proxy options or launch separate browsers. Choose based on isolation requirements and resource cost, then document the boundary.

For account or checkout testing, keep one stable endpoint for the context. For independent public screenshots, allocate a new proxy at job start if the workflow permits it. The proxy pool guide covers health checks, quarantine and replacement without making every browser worker invent its own policy.

Performance and bandwidth controls

Browser automation loads scripts, styles, images, fonts and third-party resources. That consumes more bandwidth than an API request. Measure complete page time and response errors through the actual target. Do not assume that the fastest IP-check result will be fastest for a complex application.

Puppeteer’s request interception can block unnecessary assets in an approved performance test, but it changes page behavior and can disable useful evidence. Use a named test mode and compare it with a full-page control. Never block resources merely to hide a broken layout or missing content.

• Set navigation and operation timeouts separately.
• Bound concurrent browsers and contexts.
• Record bytes or request count when bandwidth matters.
• Close idle pages and contexts promptly.
• Retain screenshots and traces only as long as required.
• Respect target rate limits and permitted test schedules.

The bandwidth and concurrency guide helps translate page weight and simultaneous sessions into a realistic proxy plan.

Troubleshoot Puppeteer proxy errors

Listen to request failures, response status and console errors, but redact authorization data. The proxy error guide helps distinguish transport, authentication, destination and gateway failures.

A maintainable Puppeteer proxy worker

1. Acquire a healthy proxy from a central pool and reserve it for the job.
2. Launch the browser or context with the endpoint and a narrow bypass list.
3. Apply credentials before the first request.
4. Verify the exit IP and expected location.
5. Run the authorized test with bounded timeouts and clear assertions.
6. Capture evidence with credentials and private data removed.
7. Close page, context and browser in a finally block.
8. Return, quarantine or replace the endpoint based on classified results.

For a broader JavaScript HTTP client setup, use the Node.js proxy guide. For cross-browser testing and integrated traces, compare the Playwright proxy guide. Do not duplicate proxy allocation logic in every automation script.