Tutorials 5 min read

Node.js Proxy Guide: axios, Puppeteer and fetch (undici) in 2026

Working, current code for using authenticated proxies in Node.js with axios, Puppeteer and fetch, plus how to keep one sticky IP per browser.

Setting up a Node.js proxy with axios or Puppeteer trips people up for the same reasons: the axios proxy option behaves badly with HTTPS, Chrome's --proxy-server flag ignores credentials, and Node's built-in fetch ignores proxy settings entirely. This guide gives you working code for all three: axios with https-proxy-agent, Puppeteer with page.authenticate, and fetch via undici's ProxyAgent, plus how to keep one sticky IP per browser.

The Connection String

http://USERNAME:[email protected]:8080

Targeting and session options go in the username: USERNAME-country-us for US exits, USERNAME-session-abc123-time-10 for a sticky IP for 10 minutes. If your password has special characters, wrap it in encodeURIComponent() when building the URL, or you'll get a 407 error. The examples below read credentials from environment variables:

export NP_USER="USERNAME"
export NP_PASS="PASSWORD"

axios With a Proxy (https-proxy-agent)

axios has a built-in proxy option, but for HTTPS targets it doesn't reliably set up a CONNECT tunnel. The dependable approach is to pass an agent and disable axios's own proxy handling with proxy: false. Current versions of https-proxy-agent (v7 and later) export a named class that takes the proxy URL directly:

// npm install axios https-proxy-agent
import axios from "axios";
import { HttpsProxyAgent } from "https-proxy-agent";

const user = process.env.NP_USER;
const pass = encodeURIComponent(process.env.NP_PASS);
const proxyUrl = "http://" + user + "-country-us:" + pass + "@global.nodeproxies.xyz:8080";

const agent = new HttpsProxyAgent(proxyUrl);

const res = await axios.get("https://api.ipify.org?format=json", {
  httpsAgent: agent,
  proxy: false,
  timeout: 20000,
});
console.log(res.data); // { ip: "..." }

Note that the proxy URL itself starts with http://, because the connection to the gateway is plain HTTP; the agent then opens an encrypted tunnel to the HTTPS site. To also proxy plain http:// URLs, install http-proxy-agent and pass new HttpProxyAgent(proxyUrl) as httpAgent.

For many requests, create one axios instance with the agent attached:

const client = axios.create({ httpsAgent: agent, proxy: false, timeout: 20000 });
const { data } = await client.get("https://example.com/");

Puppeteer With an Authenticated Proxy

Chrome takes the proxy server as a launch argument, but the --proxy-server flag can't carry a username and password. Puppeteer solves this with page.authenticate(), which answers the proxy's authentication challenge for that page:

// npm install puppeteer
import puppeteer from "puppeteer";

const browser = await puppeteer.launch({
  args: ["--proxy-server=http://global.nodeproxies.xyz:8080"],
});

const page = await browser.newPage();
await page.authenticate({
  username: process.env.NP_USER + "-country-us",
  password: process.env.NP_PASS,
});

await page.goto("https://api.ipify.org");
console.log(await page.evaluate(() => document.body.innerText));

await browser.close();

Call authenticate before the first navigation, and on every new page you open. Don't URL-encode the password here; it's passed as a plain value, not inside a URL. Use the HTTP port rather than SOCKS5, because Chrome doesn't support SOCKS5 authentication.

One Sticky Session per Browser

Without a session option, each request can exit from a different IP. A real browser loads dozens of resources per page, so a rotating IP inside one browsing session looks odd to most sites and breaks logins. Give each browser its own sticky session ID:

import crypto from "node:crypto";
import puppeteer from "puppeteer";

async function launchWithStickyIp(minutes = 30) {
  const sid = crypto.randomBytes(4).toString("hex");
  const browser = await puppeteer.launch({
    args: ["--proxy-server=http://global.nodeproxies.xyz:8080"],
  });
  const creds = {
    username: process.env.NP_USER + "-country-us-session-" + sid + "-time-" + minutes,
    password: process.env.NP_PASS,
  };
  const newPage = async () => {
    const page = await browser.newPage();
    await page.authenticate(creds);
    return page;
  };
  return { browser, newPage, sid };
}

const a = await launchWithStickyIp();
const b = await launchWithStickyIp();
const pa = await a.newPage();
const pb = await b.newPage();
await pa.goto("https://api.ipify.org");
await pb.goto("https://api.ipify.org");
console.log(a.sid, await pa.evaluate(() => document.body.innerText));
console.log(b.sid, await pb.evaluate(() => document.body.innerText));
await a.browser.close();
await b.browser.close();

Two browsers, two session IDs, two stable IPs. Keeping one identity per browser process is the simplest way to make sure Chrome never reuses a connection authenticated with a different session. If a job runs longer than the session time, pick a time that covers it. The same idea in Python is shown in our Playwright guide.

fetch With a Proxy (undici ProxyAgent)

Node's built-in fetch is powered by undici but doesn't read proxy settings on its own. Install the undici package and pass a ProxyAgent as the dispatcher. Import fetch from the same package so the versions match:

// npm install undici
import { fetch, ProxyAgent } from "undici";

const user = process.env.NP_USER;
const pass = encodeURIComponent(process.env.NP_PASS);
const dispatcher = new ProxyAgent("http://" + user + ":" + pass + "@global.nodeproxies.xyz:8080");

const res = await fetch("https://api.ipify.org?format=json", { dispatcher });
console.log(await res.json());

Credentials in the URL are turned into a Proxy-Authorization header. You can also set a global dispatcher with setGlobalDispatcher(dispatcher) from undici if every request in your process should use the proxy.

Common Node.js Proxy Mistakes

  • Using axios's proxy option for HTTPS instead of an agent plus proxy: false.
  • Old https-proxy-agent examples that call the default export as a function. Since v7 it's a named export used with new.
  • Putting credentials in --proxy-server for Puppeteer. Chrome ignores them; use page.authenticate.
  • Generating a new session ID on every request when you wanted a sticky IP.
  • Running high concurrency against one site. Throttle requests to stay within the site's limits; see how to avoid getting blocked.

Running This on NodeProxies

Copy your username and password from the dashboard's proxy generator, or build option strings with the proxy username builder. For scraping protected sites, residential proxies start at $0.65/GB; for high-volume jobs against tolerant sites, datacenter starts at $0.42/GB. There's no subscription, and you can create an account and pay with card or crypto. Full option reference is in the docs.

FAQ

Why doesn't axios work with my HTTPS proxy?

axios's built-in proxy option doesn't reliably tunnel HTTPS. Use https-proxy-agent as httpsAgent and set proxy: false.

How do I use a proxy with username and password in Puppeteer?

Launch Chrome with --proxy-server=http://host:port, then call page.authenticate({ username, password }) on each page before navigating.

Does Node.js fetch support proxies?

Not on its own. Use undici's ProxyAgent as the dispatcher option, importing fetch from undici.

How do I rotate proxies in Puppeteer?

Use the rotating username for a new IP per request, or launch a new browser with a new session ID when you want a new sticky identity.

NodeProxies

Ready to get started?

90M+ residential, mobile & datacenter proxies. Datacenter from $0.30/GB, residential from $0.42/GB. No contracts.

Create free account