Node.js Proxy Guide: Fetch, Axios, Undici and Environment Variables

Built-in Node.js proxy support

For the built-in HTTP stack, Node documents NODE_USE_ENV_PROXY=1 and --use-env-proxy from Node 24.5.0 and the 22.21.0 backport. Check node --version in the process that runs the application before using this startup example; an older 22.x or 24.x patch release may not provide the same support. The feature is still marked active development in the official command-line reference, reviewed 13 October 2026.

# Linux or macOS: each startup command is one line
NODE_USE_ENV_PROXY=1 HTTPS_PROXY="http://user:pass@proxy.example:8080" NO_PROXY="localhost,127.0.0.1,.internal.example" node app.mjs

# Or use the command-line flag
HTTPS_PROXY="http://proxy.example:8080" node --use-env-proxy app.mjs

const response = await fetch('https://api.ipify.org?format=json', {
  signal: AbortSignal.timeout(30_000)
});

if (!response.ok) {
  throw new Error(`IP check failed with ${response.status}`);
}

console.log(await response.json());

Node documents lower- and uppercase proxy variables and their precedence. Its native http/https agents support exact hosts, suffixes, wildcards, IPs, IPv4 ranges and host-port pairs in NO_PROXY. Built-in fetch and Undici EnvHttpProxyAgent use a different matcher; do not assume native-agent IP-range rules apply to them. Test bypass rules in the client and version you deploy: an overly broad entry can silently send sensitive traffic directly.

Never store an authenticated proxy URL in a checked-in .env file. The official environment variables guide explains process.env and dotenv syntax, but secret storage and deployment permissions remain your responsibility.

Use Undici EnvHttpProxyAgent

Undici’s EnvHttpProxyAgent reads HTTP, HTTPS and NO_PROXY values and can be supplied as a local dispatcher or installed globally. A local dispatcher makes the routing decision explicit for one request group.

import {
  EnvHttpProxyAgent,
  fetch
} from 'undici';

const dispatcher = new EnvHttpProxyAgent();

try {
  const response = await fetch(
    'https://api.ipify.org?format=json',
    {
      dispatcher,
      signal: AbortSignal.timeout(30_000)
    }
  );

  if (!response.ok) {
    throw new Error(`Unexpected status ${response.status}`);
  }

  console.log(await response.json());
} finally {
  await dispatcher.close();
}

The official EnvHttpProxyAgent documentation describes variable precedence, bypass matching and local or global dispatcher use. Close a locally created dispatcher during application shutdown so connections do not remain open unexpectedly.

Configure an HTTP proxy in Axios

Axios exposes a request-level proxy object for HTTP proxy routing in Node.js. This is useful when one client instance owns the policy. Do not also install a conflicting global agent unless you understand which option wins.

import axios from 'axios';

const client = axios.create({
  timeout: 30_000,
  proxy: {
    protocol: 'http',
    host: process.env.PROXY_HOST,
    port: Number(process.env.PROXY_PORT),
    auth: process.env.PROXY_USERNAME
      ? {
          username: process.env.PROXY_USERNAME,
          password: process.env.PROXY_PASSWORD || ''
        }
      : undefined
  }
});

try {
  const { data, status } = await client.get('https://api.ipify.org?format=json');
  console.log(status, data);
} catch (error) {
  const status = Number.isInteger(error.response?.status)
    ? error.response.status
    : 'unavailable';
  console.error('Proxy request failed; HTTP status:', status);
  process.exitCode = 1;
}

The official Axios request configuration documents proxy and environment behavior. SOCKS usually requires a compatible agent rather than the HTTP proxy object. Confirm the library and agent documentation instead of changing the protocol label in a URL and assuming support.

Runtime checks: 14 October 2026

We checked these request examples on Windows with Node.js 24.17.0, its bundled Undici 7.28.0, imported Undici 7.30.0 and Axios 1.20.0. Controlled local HTTP and HTTPS services and an authenticated HTTP proxy fixture recorded the request route. These checks used synthetic credentials and a synthetic IP response; they do not measure a BuyProxies exit or pool.

Each client was checked with HTTP and HTTPS success, incorrect proxy authentication, an untrusted target certificate, target status 403, a same-fixture redirect and the unchanged 30-second timeout. Certificate verification stayed enabled; successful HTTPS checks added an ephemeral fixture CA to the child process trust. The corrected Axios example printed no synthetic authentication data in any of its eight controls.

Two separate native-agent diagnostics confirmed that Node’s native HTTP agent matched the IPv4 dash range, while its native HTTPS agent connected directly when only HTTP_PROXY was set. These diagnostics are distinct from the fetch examples. Compare the versioned Node HTTP reference and Undici environment-agent documentation when choosing a bypass rule.

The POSIX startup commands were checked through equivalent process environment and flag settings on Windows; their Linux/macOS shell syntax was not executed. HTTPS proxies, SOCKS, other Node or package versions, real external exits and production throughput were not tested.

Design NO_PROXY rules carefully

NO_PROXY is a routing policy, not a convenience string. Add local development hosts, private services or destinations that must connect directly only when that behavior is intentional. Test exact hosts, subdomains and ports separately.

Log whether a request used the named routing policy, but do not log the full authenticated proxy URL. A safe record includes a masked proxy ID, destination hostname, bypass decision, duration, status and error category.

Handle Node.js proxy errors without losing evidence

• Use a total timeout or AbortSignal for every external request.
• Preserve error code, cause and proxy stage before wrapping the error.
• Distinguish proxy 407 from target 401 or 403.
• Do not retry DNS, TLS and authentication failures identically.
• Retry only safe operations with bounded backoff and jitter.
• Respect 429 and Retry-After from the target service.
• Close custom agents and dispatchers during shutdown.

A connection timeout can come from DNS, proxy reachability, the CONNECT tunnel or target. Test the proxy separately with the proxy tester, then reproduce one request with the cURL proxy guide. The error code guide helps classify the result.

Proxy pools and request assignment

A Node.js service should acquire proxies from one pool component rather than choosing a random array entry in every function. The pool owns health state, location, concurrency, quarantine and credentials. A request receives a lease, uses the proxy for the required session, records the result and releases the lease.

For a stateful sequence, reuse the same dispatcher or proxy assignment. For independent read requests, a new job may receive a different healthy proxy. Connection reuse can keep traffic on an existing route, so rotation must happen at a boundary the HTTP client actually respects.

Use proxy pool management for health and quarantine, and proxy pool sizing for concurrency and reserve. Do not use a larger pool to evade a destination’s rate limit.

For deployment, the Docker proxy guide separates container proxy settings from application configuration. If the same request is part of a visual automation, follow the n8n HTTP Request proxy walkthrough.

Credential and logging checklist

• Store proxy credentials in a secret manager or protected runtime environment.
• Encode URL username and password safely when constructing a URL.
• Redact Proxy-Authorization and authenticated URLs from errors.
• Restrict secret access to the service and environment that need it.
• Rotate credentials when staff, runners or deployments change.
• Do not return proxy configuration to browser clients.
• Use the authentication guide to choose password or IP allowlisting.

For API-focused workflows, continue with Proxies for API Testing. For browser execution, use the dedicated Playwright or Puppeteer guides rather than forcing a server-side HTTP agent into a browser process.