Puppeteer Proxy Setup: Auth, Rotation and SOCKS5 (Code)

Run one request through the gateway before you open Puppeteer. If this fails, the problem is the credentials or your network, not your script.

curl -x gate.proxyfield.io:7000 -U "<login>-country-us-city-new_york:<password>" https://api.ipify.org

Replace <login> and <password> with your ProxyField username and password. You should see an IP that is not yours. Check its country with https://ipinfo.io/json, or test your proxy with the ProxyField proxy checker. More flags are in the cURL proxy guide.

Pass the gateway to Chrome with --proxy-server, then give the page your username and password with page.authenticate():

// npm i puppeteer
const puppeteer = require('puppeteer');

const { PROXY_USER, PROXY_PASS } = process.env; // your ProxyField username and password

(async () => {
  const browser = await puppeteer.launch({
    args: ['--proxy-server=http://gate.proxyfield.io:7000'],
  });
  const page = await browser.newPage();
  await page.authenticate({
    username: `${PROXY_USER}-country-us`,
    password: PROXY_PASS,
  });
  await page.goto('https://api.ipify.org?format=json');
  console.log(await page.evaluate(() => document.body.innerText));
  await browser.close();
})();

Save it as proxy.js and run it with your credentials:

PROXY_USER=<login> PROXY_PASS=<password> node proxy.js

It prints {"ip":"..."} with a US IP. Three rules keep it working:

• No credentials in the flag. Chrome rejects a username and password inside --proxy-server: http://<login>:<password>@gate.proxyfield.io:7000 fails with net::ERR_NO_SUPPORTED_PROXIES. That is why page.authenticate exists.
• Authenticate every page. Call page.authenticate() on each new page before its first goto(). A page without it fails with net::ERR_INVALID_AUTH_CREDENTIALS.
• Targeting lives in the username. <login>-country-us exits in the United States; section 6 lists the other parameters.

To set a proxy for your everyday browser instead of a script, see Chrome proxy settings.

Which npm packages a Puppeteer proxy needs

Only puppeteer for an HTTP proxy with a username and password: --proxy-server and page.authenticate() are built in. Two more packages help in special cases.

For Node.js requests without a browser, such as fetch, see the Node.js proxy setup .

browser.createBrowserContext({ proxyServer }) gives each browser context its own proxy, so one browser can exit in several countries at once. The method is createBrowserContext() in Puppeteer 22 and later; older versions called it createIncognitoBrowserContext().

const puppeteer = require('puppeteer');

const { PROXY_USER, PROXY_PASS } = process.env;

async function checkIp(browser, country) {
  const context = await browser.createBrowserContext({
    proxyServer: 'http://gate.proxyfield.io:7000',
  });
  const page = await context.newPage();
  await page.authenticate({
    username: `${PROXY_USER}-country-${country}`,
    password: PROXY_PASS,
  });
  await page.goto('https://api.ipify.org?format=json');
  console.log(country, await page.evaluate(() => document.body.innerText));
  await context.close();
}

(async () => {
  const browser = await puppeteer.launch();
  await Promise.all([checkIp(browser, 'us'), checkIp(browser, 'gb')]);
  await browser.close();
})();

gb is the United Kingdom (<login>-country-gb). Countries take their two-letter code in lowercase, as in <login>-country-gb.

Each context has its own cookies, cache and connections, and page.authenticate() still runs once per page. The script prints two lines, one IP per country.

With ProxyField you don't keep a proxy list: the gateway gives a new IP on every request, and a sticky session holds one IP from 30 s up to 36 h. In Puppeteer, the connection decides which IP you get.

const puppeteer = require('puppeteer');

const { PROXY_USER, PROXY_PASS } = process.env;
const urls = [
  'https://api.ipify.org?format=json',
  'https://api.ipify.org?format=json',
  'https://api.ipify.org?format=json',
];

(async () => {
  const browser = await puppeteer.launch();
  for (const url of urls) {
    // A new context opens new connections, so the gateway can assign a new IP.
    const context = await browser.createBrowserContext({
      proxyServer: 'http://gate.proxyfield.io:7000',
    });
    const page = await context.newPage();
    await page.authenticate({ username: `${PROXY_USER}-country-us`, password: PROXY_PASS });
    await page.goto(url);
    console.log(await page.evaluate(() => document.body.innerText));
    await context.close();
  }
  await browser.close();
})();

A socks5:// address in --proxy-server works, but only without credentials: Chrome can't send a SOCKS5 username and password, and page.authenticate() doesn't apply to SOCKS5. You have two options.

Option 1: allowlist your IP. Add the IP of the machine that runs Puppeteer to the allowlist in your dashboard, then connect without a username to the port you set up in the dashboard (<port> below):

const puppeteer = require('puppeteer');

(async () => {
  // Works when your IP is on the allowlist: Chrome sends no SOCKS5 credentials.
  // <port> is the port you set up in the dashboard for your allowlisted IP.
  const browser = await puppeteer.launch({
    args: ['--proxy-server=socks5://gate.proxyfield.io:<port>'],
  });
  const page = await browser.newPage();
  await page.goto('https://api.ipify.org?format=json');
  console.log(await page.evaluate(() => document.body.innerText));
  await browser.close();
})();

// npm i puppeteer proxy-chain
const puppeteer = require('puppeteer');
const proxyChain = require('proxy-chain');

const { PROXY_USER, PROXY_PASS } = process.env;

(async () => {
  // A local proxy without auth that forwards to the gateway with your credentials.
  const upstream = `socks5://${encodeURIComponent(PROXY_USER)}:${encodeURIComponent(PROXY_PASS)}@gate.proxyfield.io:7000`;
  const localProxy = await proxyChain.anonymizeProxy(upstream);

  const browser = await puppeteer.launch({ args: [`--proxy-server=${localProxy}`] });
  const page = await browser.newPage();
  await page.goto('https://api.ipify.org?format=json');
  console.log(await page.evaluate(() => document.body.innerText));
  await browser.close();
  await proxyChain.closeAnonymizedProxy(localProxy, true);
})();

Targeting goes in the username. ProxyField targets by country, region (state) and city, and covers all 50 US states.

ASN, ZIP and carrier targeting are not offered. See the product pages for residential proxies and mobile 4G/5G proxies.

Billing is per GB, so every image, font and video a page loads costs traffic. If your script needs only the HTML or the text, block the rest:

const puppeteer = require('puppeteer');

const { PROXY_USER, PROXY_PASS } = process.env;
const BLOCKED = ['image', 'font', 'media'];

(async () => {
  const browser = await puppeteer.launch({
    args: ['--proxy-server=http://gate.proxyfield.io:7000'],
  });
  const page = await browser.newPage();
  await page.authenticate({ username: `${PROXY_USER}-country-us`, password: PROXY_PASS });
  await page.setRequestInterception(true);
  page.on('request', (request) => {
    if (BLOCKED.includes(request.resourceType())) request.abort();
    else request.continue();
  });
  await page.goto('https://example.com');
  console.log(await page.title());
  await browser.close();
})();

Request interception works alongside page.authenticate(). The dashboard shows your usage in real time and the gigabytes you have left, so you can compare a run with and without blocking.

Set the user agent with page.setUserAgent() and other headers with page.setExtraHTTPHeaders(), before page.goto():

const puppeteer = require('puppeteer');

const { PROXY_USER, PROXY_PASS } = process.env;

(async () => {
  const browser = await puppeteer.launch({
    args: ['--proxy-server=http://gate.proxyfield.io:7000'],
  });
  const page = await browser.newPage();
  await page.authenticate({ username: `${PROXY_USER}-country-us`, password: PROXY_PASS });
  await page.setUserAgent({
    userAgent: 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/155.0.0.0 Safari/537.36',
  });
  await page.setExtraHTTPHeaders({ 'Accept-Language': 'en-US,en;q=0.9' });
  await page.goto('https://httpbin.org/headers');
  console.log(await page.evaluate(() => document.body.innerText));
  await browser.close();
})();

// npm i puppeteer puppeteer-extra puppeteer-extra-plugin-stealth
const puppeteer = require('puppeteer-extra');
const StealthPlugin = require('puppeteer-extra-plugin-stealth');

puppeteer.use(StealthPlugin());

const { PROXY_USER, PROXY_PASS } = process.env;

(async () => {
  const browser = await puppeteer.launch({
    args: ['--proxy-server=http://gate.proxyfield.io:7000'],
  });
  const page = await browser.newPage();
  await page.authenticate({ username: `${PROXY_USER}-country-us`, password: PROXY_PASS });
  await page.goto('https://api.ipify.org?format=json');
  console.log(await page.evaluate(() => document.body.innerText));
  await browser.close();
})();

net::ERR_TUNNEL_CONNECTION_FAILED means Chrome reached the proxy, but the proxy answered the tunnel (CONNECT) request with an error instead of connecting to the site. Check the scheme, the credentials, whether the site is up, and whether it falls in a restricted category.

Puppeteer is a Node.js library; in Python, the Playwright proxy setup takes the same gateway (more in our Puppeteer guide ).

Start with the Easy Trial: 1 GB for $2.95, no minimum purchase, no subscription, and the traffic never expires. All purchases are final. See pricing per GB.

The same --proxy-server setup works in headless and headed mode; other headless tools are covered in our proxy setup hub and the alternatives to Puppeteer in our Puppeteer alternatives guide .