Puppeteer Proxy Authentication: HTTP, 407 Errors, and Context Isolation

Proxy authentication failures in Puppeteer are often caused by mixing three separate settings: where the proxy server is configured, where proxy credentials are supplied, and where target-site authentication is supplied.

Install Puppeteer

mkdir puppeteer-proxy-example
cd puppeteer-proxy-example
npm init -y
npm install puppeteer

Store secrets outside source code:

PROXY_SERVER=http://proxy.example.com:8001
PROXY_USERNAME=customer-123-country-US
PROXY_PASSWORD=replace-me
IP_CHECK_URL=https://iprobe.io/json

Option 1: browser-level proxy

import puppeteer from 'puppeteer';

const server = process.env.PROXY_SERVER;
const username = process.env.PROXY_USERNAME;
const password = process.env.PROXY_PASSWORD;

if (!server) throw new Error('Missing PROXY_SERVER');

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

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

  if (username || password) {
    if (!username || !password) {
      throw new Error('Set both PROXY_USERNAME and PROXY_PASSWORD');
    }
    await page.authenticate({ username, password });
  }

  const response = await page.goto(
    process.env.IP_CHECK_URL || 'https://iprobe.io/json',
    { waitUntil: 'domcontentloaded', timeout: 45_000 },
  );

  if (!response) throw new Error('Navigation returned no response');

  console.log({
    status: response.status(),
    finalUrl: page.url(),
    body: await page.$eval('body', el => el.innerText),
  });
} finally {
  await browser.close();
}

Puppeteer's official LaunchOptions documents the args field, and Page.authenticate() documents HTTP authentication credentials. The method enables request interception internally, which can affect performance. See LaunchOptions↗ and Page.authenticate↗.

Option 2: proxy per BrowserContext

Current Puppeteer documentation exposes proxyServer and proxyBypassList in BrowserContextOptions. A BrowserContext also isolates cookies and local storage from other contexts, which makes it a useful boundary for independent proxy-backed workflows.

import puppeteer from 'puppeteer';

function requiredEnv(name) {
  const value = process.env[name]?.trim();
  if (!value) throw new Error(`Missing ${name}`);
  return value;
}

const server = requiredEnv('PROXY_SERVER');
const username = process.env.PROXY_USERNAME?.trim();
const password = process.env.PROXY_PASSWORD?.trim();

if (Boolean(username) !== Boolean(password)) {
  throw new Error('Set both PROXY_USERNAME and PROXY_PASSWORD, or neither');
}

const browser = await puppeteer.launch({ headless: true });

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

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

    if (username && password) {
      await page.authenticate({ username, password });
    }

    const response = await page.goto(
      process.env.IP_CHECK_URL || 'https://iprobe.io/json',
      { waitUntil: 'domcontentloaded', timeout: 45_000 },
    );

    if (!response) throw new Error('Navigation returned no response');

    console.log({
      status: response.status(),
      finalUrl: page.url(),
      body: await page.$eval('body', el => el.innerText),
    });
  } finally {
    await context.close();
  }
} finally {
  await browser.close();
}

See BrowserContextOptions↗, Browser.createBrowserContext↗, and Page.authenticate↗.

407 versus 401

• 407 Proxy Authentication Required is a proxy-authentication challenge. RFC 9110 requires a proxy-generated 407 to include a Proxy-Authenticate challenge.
• 401 Unauthorized is an origin-server authentication challenge and uses WWW-Authenticate instead.

Do not solve a 407 by filling a target-site login form or changing target cookies. Do not solve an origin 401 by blindly rotating proxy credentials. Preserve the response status and authentication headers in your diagnostic evidence, but redact secrets before logging them.

See RFC 9110: HTTP Semantics↗.

Why credentials in the proxy URL can fail

Embedding username:password@host can leak secrets through logs and can break when special characters are encoded incorrectly. Prefer a server-only proxy setting plus Page.authenticate() for HTTP proxy credentials.

Verify outside Puppeteer first

curl --proxy 'http://proxy.example.com:8001' \
  --proxy-user 'customer-123-country-US:replace-me' \
  --connect-timeout 15 \
  --max-time 30 \
  'https://iprobe.io/json'

Interpret the comparison:

• curl and Puppeteer both return 407: credential or account issue
• curl works and Puppeteer returns 407: configuration, timing, version, or injection issue
• both fail before HTTP: DNS, connection, protocol, firewall, or availability
• IP check works but target rejects: target behavior, not basic connectivity

Set authentication before navigation

Call page.authenticate() before the first request that must use the proxy. Pages, workers, popups, and downloads can create additional requests. For a context with multiple pages, authenticate each page that may receive an HTTP challenge.

HTTP and SOCKS behavior

Puppeteer's current BrowserContextOptions documentation says proxyServer can be used for the context and that username/password can be supplied through Page.authenticate(). Page.authenticate() itself is documented as HTTP authentication and enables request interception internally.

Do not infer from that API that every authenticated SOCKS deployment will behave the same way. For SOCKS endpoints, validate the exact scheme, authentication method, Chromium/Puppeteer version, proxy endpoint, and DNS behavior before production use. If your provider publishes protocol-specific connection instructions, treat those instructions as provider-specific rather than as a Puppeteer guarantee.

Rotating and sticky sessions

Puppeteer does not create rotation by itself. The proxy service interprets the username, session token, or endpoint.

Use rotating sessions for independent snapshots. Use sticky sessions for login, forms, carts, account navigation, and any workflow where cookies and IP should remain coherent. Keep one BrowserContext and one proxy session for one stateful workflow.

Geography is more than the IP

Align requested proxy geography, visible exit location, browser locale, timezone, URL market parameters, account region, and cookies. Validate the actual currency, inventory, language, or search result.

Diagnostic events

page.on('requestfailed', request => {
  console.error('request_failed', {
    url: request.url(),
    error: request.failure()?.errorText,
  });
});

page.on('response', response => {
  if (response.status() >= 400) {
    console.warn('http_error', {
      status: response.status(),
      url: response.url(),
    });
  }
});

A request receiving HTTP 403, 407, or 503 is different from a request failing before any HTTP response.

Retry classification

Production checklist

1. Pin the Puppeteer version.
2. Test credentials with curl.
3. Configure proxy at browser or context level.
4. Authenticate before navigation.
5. Verify the visible exit IP.
6. Keep secrets out of logs.
7. Use bounded context concurrency.
8. Classify 407 separately from target responses.
9. Preserve one context for one sticky workflow.
10. Close resources in finally blocks.

What the proxy does—and does not—change

A proxy changes the network path and the source IP visible to destinations reached through that path. It does not automatically synchronize or replace browser cookies, local storage, account history, JavaScript-visible browser properties, TLS implementation details, device characteristics, or every signal a destination may use for risk decisions.

For geography-sensitive workflows, treat the exit IP as one input. Verify the actual business result you care about—such as locale, currency, inventory, or page content—rather than assuming an IP lookup alone proves the workflow is correct.

Authorization and stop conditions

Use browser automation and proxies only where you are authorized to access and automate the target. Respect applicable terms, privacy requirements, access controls, and rate limits.

Stop and require review when:

• the workflow would require bypassing an explicit access or security control;
• repeated 403/429/challenge responses indicate the target is refusing or constraining automation;
• you cannot establish that collection or automated access is permitted;
• credentials, personal data, or downloaded files would cross an unapproved trust boundary.

Changing proxy routes is not a substitute for resolving an authorization or policy problem.

FAQ

Should I put username:password inside --proxy-server?

Prefer keeping secrets out of launch arguments and logs. For HTTP proxy authentication, configure the proxy server separately and provide credentials with Page.authenticate() when supported by your path.

Why does curl work while Puppeteer returns 407?

That usually narrows the problem to the browser-side configuration rather than proving the proxy is unavailable. Check that authentication runs before navigation, confirm the Puppeteer/Chrome versions, verify the proxy scheme, and compare the exact endpoint and credentials used by both clients.

Can one BrowserContext use a different proxy from another?

Current Puppeteer documentation exposes proxyServer on BrowserContextOptions. Use separate contexts when you need isolated storage and independently configured proxy routes, then close each context when its workflow finishes.

Does changing the proxy make the browser look like a different device?

No. A proxy changes network routing and the observable source IP for proxied traffic; it does not by itself replace the rest of the browser or device state.

Should I rotate the proxy after every 403 or 429?

No. First classify the response and review authorization, request rate, session state, target policy, and application behavior. Repeatedly changing IPs to evade an explicit restriction is not an appropriate default recovery strategy.

Related BytesFlows resources

• How to use proxies with Playwright
• Playwright proxy errors
• Browser automation proxies
• Proxy credential redaction
• Residential proxies

Source and test boundary

API statements are grounded in the current Puppeteer documentation linked above. The examples were not executed during publication and should be tested against your pinned Puppeteer and Chrome versions in an authorized environment.