Proxies for Puppeteer

It almost always means credentials ended up inside the --proxy-server value. Chrome doesn't parse user:pass@IP:port there — it treats the whole string as an unsupported proxy scheme and refuses to route anything. Strip the string down to IP:port and the error disappears. Then authenticate one of two ways: call page.authenticate({username, password}) before the first goto() on every page you create, or whitelist your server's IP in the Dashboard and skip credentials entirely — the second option is one less call per page and the only one that also covers SOCKS5.

No. page.authenticate() answers HTTP auth challenges, and Chrome has no mechanism for SOCKS5 credentials at all — the Puppeteer feature request (issue #4170) has been open since 2019 with no plans to implement it. The community workarounds are proxy-chain (a local hop that strips authentication) or forks of puppeteer-page-proxy, both of which add moving parts to every request. With IP whitelisting the limitation simply doesn't apply: --proxy-server=socks5://IP:port connects with no credentials to negotiate, and every address in our packages answers on HTTP, HTTPS, SOCKS4, and SOCKS5 alike.

Per page — not natively; that's exactly the gap the puppeteer-page-proxy plugin tried to fill by re-routing requests in JavaScript. The supported unit is the browser context: browser.createBrowserContext({ proxyServer: 'IP:port' }) gives you an isolated session — separate cookies, storage, and exit IP — inside a single Chrome process. One context per account or task is the pattern: dozens of contexts cost far less RAM than dozens of browsers. Assign each context its own address from your package list, and with whitelisted IPs the contexts need no authentication calls at all.

Rotating proxies for Puppeteer work at two levels, and neither requires restarting Chrome per address. The self-managed way: export your package list and cycle through it — a new address per puppeteer.launch(), or per browser context if you're running many tasks in one process. That's a few lines of code and keeps per-IP costs at package prices. The managed way: point --proxy-server at a rotating plan's gateway once, and the exit IP changes on our side per request — no list handling, but billing shifts from per-IP to per-request, which only pays off when you genuinely need thousands of distinct exits. What doesn't work is trying to swap the proxy of an already-running context: the flag is fixed at creation, so rotation always means a new context, not a mutation.

The proxy flag itself behaves identically — --proxy-server works the same headless and headful. Two practical notes. First, in headless mode a proxy auth failure is invisible: there's no popup, requests just die with ERR_TUNNEL_CONNECTION_FAILED, which is why credential-free whitelisting saves the most debugging time exactly where most Puppeteer fleets run. Second, in Docker remember that the IP to whitelist is the egress IP of the host (or NAT gateway), not the container's internal address — check what the outside world sees with curl ifconfig.me from inside the container before adding it in the Dashboard.