Puppeteer Proxies: Why Chromium Ignores Your Password, and What to Do About It

If you only need the working setup, the Puppeteer integration page has it. This article is about the constraint underneath it, because that constraint determines your architecture rather than just your configuration.

What actually happens

// Looks reasonable. Chromium throws the credentials away.
const browser = await puppeteer.launch({
  args: ["--proxy-server=http://USERNAME:PASSWORD@PROXY_HOST:PROXY_PORT"],
});

Chromium parses that flag as a host and port and ignores everything before the @. The first navigation reaches the proxy without a Proxy-Authorization header, the proxy replies with a 407 challenge, and Chromium — having no credentials to offer — renders an error page. Nothing in the launch call warned you.

const browser = await puppeteer.launch({
  args: ["--proxy-server=http://PROXY_HOST:PROXY_PORT"],
});

const page = await browser.newPage();
await page.authenticate({ username: "USERNAME", password: "PASSWORD" });
await page.goto("https://api.ipify.org?format=json");

The constraint that shapes everything else

The proxy is a browser-process launch flag, so it cannot be changed at runtime. Puppeteer has no equivalent of Playwright's per-context proxy: browser.createIncognitoBrowserContext() isolates cookies and storage, but every context in the process still exits through the same address.

Pattern 1: one browser per identity

const crypto = require("crypto");

async function browserWithFreshExit() {
  const tag = crypto.randomBytes(4).toString("hex");
  const browser = await puppeteer.launch({
    args: ["--proxy-server=http://PROXY_HOST:PROXY_PORT"],
  });
  const page = await browser.newPage();
  await page.authenticate({
    username: `USERNAME-session-${tag}`,
    password: "PASSWORD",
  });
  return { browser, page };
}

Simple and correct, and the right answer for small concurrency. The cost is real though: a Chromium process is 100–300MB, so twenty identities is several gigabytes of RAM and twenty cold starts.

Pattern 2: a local relay

Point Chromium at http://127.0.0.1:PORT — a local proxy with no authentication — and let that process add the upstream credentials and choose the exit per connection. Chromium never learns that the exit changed, so one browser serves many identities without a restart.

• No credential handling in Chromium at all, so page.authenticate() disappears from your code.
• The exit can change per connection, driven by whatever logic you put in the relay.
• One browser process, so memory stays flat as concurrency grows.
• The relay is one more moving part, and it is now in the path of every request.

Pattern 3: per-request routing

For collecting data rather than driving a UI, the browser does not need to fetch everything. Intercept requests and pull the ones you care about with a plain HTTP client through whichever exit you like, leaving Chromium to render.

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

Verifying, and the headless tell

Confirm the exit from inside the browser, then confirm the browser does not announce itself. Old headless Chrome shipped HeadlessChrome in the User-Agent and left navigator.webdriver set to true; the modern headless mode fixed much of that, but only if you use it.

const browser = await puppeteer.launch({
  headless: "new",
  args: [
    "--proxy-server=http://PROXY_HOST:PROXY_PORT",
    "--disable-blink-features=AutomationControlled",
  ],
});

Beyond that, resist the urge to spoof aggressively. A User-Agent that disagrees with the TLS handshake or the rendered feature set is a stronger signal than the default would have been — the reasoning is set out in how to avoid getting blocked.

Symptom to cause

The whole subject reduces to one design decision: whether the browser or something in front of it owns the proxy. Puppeteer makes that decision for you at launch, which is precisely why it is worth making deliberately.