Puppeteer Proxy Setup | InstantProxies Docs

Use this guide to connect InstantProxies to Puppeteer and validate that browser traffic is actually going through the proxy.

For most users, the right goal is simple: launch Chromium with the proxy, confirm the connection works, then move into the real automation flow. Do not start with login flows, multi-page workflows, or scraping logic before the baseline browser path is proven.

Use this page when

Use this page when:

you want to use InstantProxies in Puppeteer
your workflow depends on a real browser instead of raw HTTP requests
you need browser rendering, JavaScript execution, or page state
you want to verify that Puppeteer is actually using the proxy before building a larger workflow

If your workload is mostly request-based, use a language integration guide instead of browser automation.

Before you start

Have these details ready:

proxy host
proxy port
authentication method
a simple test URL

The two common access methods are:

username and password authentication
source IP authorization

If you are using IP authorization, make sure the public IP of the real runtime environment is already authorized.

Basic Puppeteer proxy setup

In Puppeteer, proxy configuration is usually passed at browser launch through Chromium arguments.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  headless: true,
  args: ['--proxy-server=http://YOUR_PROXY_HOST:PORT']
});

const page = await browser.newPage();
await page.goto('https://httpbin.org/ip', { waitUntil: 'networkidle2' });
console.log(await page.content());

await browser.close();

Use this first to confirm:

the browser launches successfully
Puppeteer can reach the proxy
the proxy is actually being used for browser traffic
one simple page load completes cleanly

Puppeteer setup with username and password

If your proxy uses credentials, launch the browser with the proxy server and authenticate the page before navigation.

import puppeteer from 'puppeteer';

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

const page = await browser.newPage();
await page.authenticate({
  username: process.env.INSTANTPROXIES_USERNAME,
  password: process.env.INSTANTPROXIES_PASSWORD
});

await page.goto('https://httpbin.org/ip', { waitUntil: 'networkidle2' });
console.log(await page.content());

await browser.close();

Do not hardcode credentials into source files.

Use environment variables or your normal secret-handling path instead.

Puppeteer setup with IP authorization

If your account is configured to allow traffic from an approved public IP, you can usually omit username and password.

import puppeteer from 'puppeteer';

const browser = await puppeteer.launch({
  headless: true,
  args: ['--proxy-server=http://YOUR_PROXY_HOST:PORT']
});

const page = await browser.newPage();
await page.goto('https://httpbin.org/ip', { waitUntil: 'networkidle2' });
console.log(await page.content());

await browser.close();

This works only when the real runtime environment is already authorized.

A local machine, server, container, and CI runner may all use different public IPs.

Validate the proxy before building the workflow

Before adding authentication flows, scraping logic, or multi-page automation, validate in this order:

browser launch
one simple page load
returned IP or baseline response
repeated execution of the same path
only then add real browser actions

This keeps setup issues separate from workflow issues.

If you have not yet validated the proxy outside Puppeteer, start with First Request with cURL and Authentication and Access.

Keep proxy setup separate from page logic

Do not rebuild proxy configuration inside page actions or scraping steps.

Keep these separate:

browser launch settings
proxy settings
authentication values
timeout and wait behavior
page interactions
workflow logic

This makes Puppeteer easier to debug and easier to reuse.

Be careful with page state and repeated runs

Puppeteer workflows often fail after the first successful run, not before it.

Check:

whether the same page path works repeatedly
whether browser state is being reused intentionally or accidentally
whether navigation timing changes across runs
whether cookies or session data are affecting the workflow

Repeated-run stability is a much better signal than a single successful page load.

Make waits and timeouts explicit

Puppeteer workflows depend on more than just browser launch.

You should think about timing at these boundaries:

launch
page creation
navigation
selector readiness
repeated workflow steps

A page finishing navigation does not always mean the next step is ready.

If timing is the main issue, continue to Timeouts, Retries, and Backoff.

Test repeated runs

One successful browser run is not enough.

Repeat the same simple path several times and check:

whether launch stays consistent
whether navigation timing drifts
whether page state behaves as expected
whether the same runtime still works after repeated execution

Repeated-run stability is a much better signal than first-run success.

Common Puppeteer proxy mistakes

Typical issues include:

validating only one successful page load
using the wrong runtime IP for allowlisting
forgetting page.authenticate() when credentials are required
mixing proxy configuration into page logic
hardcoding credentials
starting with a large workflow before the proxy path is validated
treating a browser workflow failure as if it were only a simple request failure

Basic troubleshooting checks

If the Puppeteer run fails, check these first:

host and port are correct
username and password are correct if used
the real runtime IP is authorized if using IP allowlisting
page.authenticate() is being used before navigation when credentials are required
the same proxy works with cURL from the same environment
the page failure happens at launch, navigation, or later in the workflow

If the problem is still unclear, continue to Authentication and Allowlist Errors or Connectivity Troubleshooting.

Recommended setup sequence

Use this sequence:

confirm the access method
configure the proxy at browser launch
add page authentication if credentials are required
validate one simple page load
repeat the same path from the same environment
make waits and timeouts explicit
only then expand into a larger Puppeteer workflow

Key points

configure the proxy at browser launch
use page.authenticate() when the proxy requires username and password
match the authentication method to the real runtime environment
validate the proxy path before building the full workflow
keep proxy setup separate from page logic
repeated runs matter more than one successful page load

Next step

If you need another browser framework, continue to Playwright Proxy Setup or Selenium Proxy Setup.

If Puppeteer launches correctly but your browser flow still fails, continue to Browser Automation Troubleshooting.