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

Built-in Node.js proxy support

On a Node release that supports it, enable environment proxy routing at startup with NODE_USE_ENV_PROXY=1 or --use-env-proxy. Then normal fetch and supported HTTP clients can read the proxy variables.

# Linux or macOS
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. It also supports exact hosts, suffixes, wildcards, IPs, ranges and host-port pairs in NO_PROXY. Test bypass rules: 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
  }
});

const { data, status } = await client.get(
  'https://api.ipify.org?format=json'
);

console.log(status, data);

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.

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.

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.