Puppeteer Proxy Setup: Auth, SOCKS5, and Rotating IPs | Proxy302

What you need before you start

A Node.js project with Puppeteer installed and a script that launches a browser.

A Proxy302 account with dynamic residential traffic. The Budget line costs US$1.50 per GB at any amount (US$1.35 per GB at 100 GB) and the smallest purchase is 1 GB; see the pricing page.

Your Proxy302 proxy username and password. The My assets page of the console shows HOST, PORT, USERNAME and PASSWORD for everything you bought.

• pricing page

• Sources:
• Proxy302 pricing
• Proxy302 guide: proxy address, port and login

The connection, field by field

Gateway host: proxy.proxy302.com — HTTP and SOCKS5 share the gateway

Port for HTTP: 2222 — the recommended endpoint for Puppeteer

Port for SOCKS5: 3333

Launch argument: --proxy-server=http://proxy.proxy302.com:2222

Authentication: await page.authenticate({ username, password }) before the first page.goto()

Where the values come from: My assets in the Proxy302 console

• Sources:
• Proxy302 guide: proxy address, port and login

A complete first script

const puppeteer = require('puppeteer');

(async () => {
  const browser = await puppeteer.launch({
    args: ['--proxy-server=http://proxy.proxy302.com:2222'],
  });

  const page = await browser.newPage();
  await page.authenticate({
    username: 'YOUR_PROXY_USERNAME',
    password: 'YOUR_PROXY_PASSWORD',
  });

  await page.goto('https://ipinfo.io/json');
  console.log('Exit:', await page.$eval('body', (el) => el.textContent));

  await browser.close();
})();

Runnable as shown: fill in your Proxy302 credentials and run with Node.js.

• Sources:
• Puppeteer API reference: LaunchOptions
• Puppeteer API reference: page.authenticate()
• Proxy302 guide: proxy address, port and login

What the launch flag does

--proxy-server is a Chromium command-line switch, documented in the Chromium source as "Uses a specified proxy server, overrides system settings." Puppeteer hands it to the browser through the args option of puppeteer.launch(), which the Puppeteer API reference describes as "Additional command line arguments to pass to the browser instance." The browser runs headless by default.

Chromium recognizes http, https, socks4 and socks5 proxy schemes, so the same flag carries either endpoint: --proxy-server=http://proxy.proxy302.com:2222 or --proxy-server=socks5://proxy.proxy302.com:3333.

• Sources:
• Chromium source: chrome/common/chrome_switches.h
• Chromium source: net/base/proxy_server.cc
• Puppeteer API reference: LaunchOptions

What page.authenticate() does

The Puppeteer API reference says page.authenticate() provides "credentials for HTTP authentication" for the page, and notes that "Request interception will be turned on behind the scenes to implement authentication." Call it before the first page.goto(), and pass null to disable it again.

This is why HTTP on port 2222 is the recommended endpoint: the browser completes the username and password log-in that every Proxy302 connection requires, inside the page itself. Use the same username and password your other tools use; they are shown in My assets.

• Sources:
• Puppeteer API reference: page.authenticate()
• Proxy302 guide: proxy address, port and login

Confirm the exit IP

Load https://ipinfo.io/json through the page. The ip and country fields should belong to the proxy exit, not to your own connection. If the printed address is your own, the launch argument did not reach the browser instance this script drives: print the exit IP first, then check which browser the script launches and configures. The proxy location guide explains the fields.

• proxy location guide

Traffic, price and expiry

Dynamic residential traffic is billed per GB on two lines: Budget from US$1.50 per GB (US$1.35 per GB at 100 GB) and Premium from US$5.00 per GB. The smallest purchase is 1 GB. Payment is prepaid, pay as you go, with no subscription, and purchased GB does not expire.

• Sources:
• Proxy302 pricing
• Proxy302: rotating residential proxies

Rotating IPs vs. sticky sessions in Puppeteer

The rotating residential product page describes two behaviors: each request goes through a different real household IP, and a sticky session holds one residential IP across a sequence of requests. Per-request rotation fits scraping many pages, price checks and any job where no single IP should build up history; a sticky session fits login flows, carts and anything session-aware.

You do not manage a proxy list: one gateway and one set of credentials carry the traffic. How a line is set to one behavior or the other is not described on the product page, so confirm it instead of assuming it: load https://ipinfo.io/json across two requests from the script and compare the exit IP — a different address each time means per-request rotation, the same address means the session is holding one IP.

• rotating residential page

• Sources:
• Proxy302: rotating residential proxies

Loop over URLs, then confirm the exit behavior

// The gateway and credentials do not change between jobs.
for (const url of urls) {
  await page.goto(url, { waitUntil: 'domcontentloaded' });
  // ...extract what you need
}

// Confirm which behavior your line uses: load an IP-echo page twice
// and compare the exit IP.
for (let i = 0; i < 2; i++) {
  await page.goto('https://ipinfo.io/json', { waitUntil: 'domcontentloaded' });
  console.log('Exit:', await page.$eval('body', (el) => el.textContent));
}

Runnable as shown: fill in your Proxy302 credentials and run with Node.js.

Using SOCKS5 with Puppeteer

The SOCKS5 endpoint is port 3333 on the same gateway. There is a catch in the browser itself: the SOCKS5 client in Chromium — the engine Puppeteer drives — sends a greeting that offers exactly one method, "no authentication", and the handshake only proceeds when the server selects it. Chromium never offers SOCKS5 username and password authentication, and every Proxy302 connection requires your username and password.

That leaves three practical paths. One: use HTTP on port 2222 — authentication works end to end through page.authenticate() as shown above, and nothing else changes. Two: run a small local forwarder on your machine that accepts the browser's unauthenticated connection and forwards it to the authenticated SOCKS5 endpoint — worth it only for jobs that need SOCKS5 specifically, since for plain web traffic the HTTP path does the same work. Three: use SOCKS5 from a tool outside the browser that implements SOCKS5 username and password authentication itself.

• Sources:
• Chromium source: net/socket/socks5_client_socket.cc
• Proxy302 guide: proxy address, port and login

SOCKS5 from outside the browser: curl

curl -x socks5h://USERNAME:[email protected]:3333 https://ipinfo.io/json

Runnable as shown: fill in your Proxy302 credentials and run with Node.js.

• Sources:
• libcurl documentation: CURLOPT_PROXY
• Proxy302 guide: proxy address, port and login

Why socks5h and not socks5

Keep the h in socks5h://. The libcurl documentation defines socks5h:// as "SOCKS5 Proxy. Proxy resolves URL hostname", while plain socks5:// resolves the hostname on your machine before contacting the proxy. Resolving on the proxy side keeps the site's view of your DNS consistent with your exit IP. The same documentation confirms the credential style scheme://username:password@hostname used in the command above.

• Sources:
• libcurl documentation: CURLOPT_PROXY

Common errors and what to check

net::ERR_NO_SUPPORTED_PROXIES: The Chromium error list describes this as "There are no supported proxies in the provided list." Check the --proxy-server value: keep a supported scheme (http:// or socks5://) and a correct host:port.

net::ERR_PROXY_CONNECTION_FAILED: "Could not create a connection to the proxy server. An error occurred either in resolving its name, or in connecting a socket to it", per the Chromium error list. Check the host spelling proxy.proxy302.com, port 2222 (HTTP) or 3333 (SOCKS5), and that your network allows outbound connections to the gateway.

HTTP 407 or repeated auth prompts: page.authenticate() must run before the first page.goto(). Re-copy the username and password with no stray spaces or line breaks.

Pages load but show your own IP: The launch argument did not reach this browser instance. Print the exit IP first, then check that the script launches the browser it configures.

Timeouts on slow targets: Raise the page.goto() timeout for the job and confirm the account still has traffic.

• Sources:
• Chromium source: net/base/net_error_list.h
• Proxy302 guide: proxy address, port and login

FAQ

Read next

Playwright proxies

Playwright proxy setup with username and password: static datacenter IPs for tests and CI, rotating residential from US$1.50/GB when a site blocks servers.

View options and pricing

Selenium proxies

Selenium proxy with username and password in Chrome: HTTP proxy in ChromeOptions plus Selenium's BiDi auth handler, no extensions. Static datacenter IPs for test runs.

View options and pricing

Proxy address, port, username and password

Every working proxy is described by five basic fields: protocol, host address, port, login, and password.

Pricing

Residential proxies from US$1.50/GB, static ISP IPs US$7.99 and datacenter IPs US$3.99 per month. Pay as you go, no subscription.