WeProxy proxy setup for Puppeteer

In Puppeteer, the proxy connection is defined with the --proxy-server parameter when Chromium launches. If a username and password are required, use page.authenticate() after opening a page. This guide is only for authorized automation, testing, and data-access scenarios; follow the target site’s terms of use and robots policies.

Install Puppeteer

npm install puppeteer

Keep WeProxy details in environment variables:

export WEPROXY_HOST="PROXY_HOST"
export WEPROXY_PORT="PROXY_PORT"
export WEPROXY_USERNAME="PROXY_USERNAME"
export WEPROXY_PASSWORD="PROXY_PASSWORD"

If you use PowerShell, use $env:VARIABLE="value" instead of export.

Authenticated HTTP Proxy Example

import puppeteer from 'puppeteer';

const {
  WEPROXY_HOST,
  WEPROXY_PORT,
  WEPROXY_USERNAME,
  WEPROXY_PASSWORD,
} = process.env;

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

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

  await page.authenticate({
    username: WEPROXY_USERNAME,
    password: WEPROXY_PASSWORD,
  });

  await page.goto('https://api.ipify.org?format=json', {
    waitUntil: 'domcontentloaded',
    timeout: 30_000,
  });

  console.log(await page.evaluate(() => document.body.innerText));
} finally {
  await browser.close();
}

Do not add the username and password to the --proxy-server parameter. Chromium does not reliably support that form, and secrets on the command line can appear in the system process list.

Using an IP-Allowlisted Proxy

If your WeProxy product supports an IP allow list, authorize your current server IP in the panel. In that case you can connect with only the host and port, without calling page.authenticate().

A Different Proxy for Each Browser

--proxy-server applies to the entire browser process. If you need different proxies, start a separate puppeteer.launch() process for each proxy. You cannot natively assign different proxies to different pages in a single browser.

Puppeteer Proxy Errors

ERR_PROXY_CONNECTION_FAILED

The host, port, protocol, or package status is wrong. First verify the proxy with the test details in the panel.

ERR_TUNNEL_CONNECTION_FAILED

The proxy may be unable to tunnel to an HTTPS destination, or authentication may be incomplete. Confirm that page.authenticate() runs before page.goto().

407 Proxy Authentication Required

The username/password is wrong, or the product expects IP authentication. Check the authentication method in the panel.

Cannot reach an IPv6 destination

If you use a WeProxy IPv6 product, confirm the target site’s IPv6 compatibility. An IPv6 proxy may not work for IPv4-only destinations.

Safe and Stable Usage Tips

• If you use credentials with a .env file, add the file to .gitignore.
• Set timeout and retry limits.
• Do not send excessive requests to the destination server.
• Choose a static, sticky, or rotating proxy session model based on your workflow.
• Make sure the automation complies with the target platform’s rules.

Source

• Puppeteer API: page.authenticate()