Coronium Mobile Proxies
Developer proxy configuration

Node.js Fetch Proxy Setup: Native Settings and Undici

Choose a supported Node.js proxy path, verify the exit IP, and avoid mixing incompatible fetch and dispatcher versions.

Coronium Technical TeamSources checked 7 min read
Illustration of queued requests passing through one proxy gateway to destination servers.
Reuse the client inside one session. The request queue, proxy connection and destination response each need their own limit.

The practical answer

  • On supported Node versions, native proxy environment support must be enabled. Setting HTTPS_PROXY alone is not enough.
  • For explicit routing, import fetch and ProxyAgent from the same Undici package and pass the dispatcher on each request.
  • A browser, a Node worker and a browser subprocess have separate network configuration. Test the process that makes the request.

Choose native routing or an explicit dispatcher

Native Node environment routing and an explicit Undici dispatcher are separate choices.
Choose one configuration owner for the request. Native fetch uses the runtime implementation; the explicit example keeps fetch and ProxyAgent in the same package.Open full-size diagram

Node.js provides two useful approaches for a server-side HTTP tool. Native environment routing fits a process whose requests share an operations-managed proxy. A per-request Undici dispatcher fits an integration that needs a specific endpoint while other requests use their own configuration.

The Node.js network guide documents native environment proxy support for fetch from v22.21.0 and v24.0.0. The --use-env-proxy flag is documented from v22.21.0 and v24.5.0. Check the version on the deployed worker with node --version, not just the version on your development machine.

The fetch API is backed by Undici. A traditional Node http.Agent or Axios proxy object is not the same configuration interface. Browser fetch is also separate: it does not accept Node dispatchers.

The examples below use Node.js 22.23.1. The explicit client was tested with Undici 8.12.1. Record both versions when filing a connection issue, because a package upgrade can change the dispatcher interface while the gateway is unchanged.

Enable native proxy settings at process startup

For a centrally configured process, provide HTTP_PROXY and HTTPS_PROXY as authenticated gateway URLs through your secret manager, and enable the native routing mode. Percent-encode reserved characters in the URL's username and password fields.

bash
# HTTP_PROXY and HTTPS_PROXY are already set privately.
export NODE_USE_ENV_PROXY=1
export NO_PROXY='localhost,127.0.0.1'
node -e 'fetch("https://api.ipify.org?format=json").then(r => r.json()).then(({ip}) => console.log(ip)).catch(() => process.exit(1))'

This minimal command prints the IP reported by ipify. Use the complete script below when you need explicit credentials, response status handling and a request deadline. The Node lab separately confirms both a proxied request and a deliberate NO_PROXY bypass.

NO_PROXY can explain a request that succeeds from an unexpected IP. Check the exact destination hostname against the bypass list. If the process chooses a request-level dispatcher, reason about that dispatcher's configuration instead of assuming that a global environment setting overrides it. The native routing guide describes the environment, bypass and agent behavior.

Install and run the explicit Undici example

Create a small project with its own lockfile:

bash
mkdir node-proxy-check
cd node-proxy-check
npm init -y
npm install --save-exact undici@8.12.1
node --version
npm ls undici

Replace the three placeholders below with the scheme, host, port and credentials shown for your connection. The gateway URL contains no username or password. These are POSIX-shell commands; use your deployment secret store for a hosted worker.

bash
export PROXY_URL='http://proxy.example:8080'
export PROXY_USER='YOUR_PROXY_USERNAME'
export PROXY_PASSWORD='YOUR_PROXY_PASSWORD'
export TARGET_URL='https://api.ipify.org?format=json'

The default diagnostic destination is ipify, which returns the public address it sees. You can set TARGET_URL to a small endpoint you control instead. A successful transport response alone does not establish a country: use the returned IP in the location checks.

javascript
// Server-side Node.js. Set PROXY_URL, PROXY_USER and PROXY_PASSWORD privately.
import { fetch, ProxyAgent } from 'undici';
import { isIP } from 'node:net';

let dispatcher;
try {
  for (const name of ['PROXY_URL', 'PROXY_USER', 'PROXY_PASSWORD']) {
    if (!process.env[name]) throw new Error(`Missing ${name}`);
  }
  const token = Buffer.from(`${process.env.PROXY_USER}:${process.env.PROXY_PASSWORD}`).toString('base64');
  dispatcher = new ProxyAgent({
    uri: process.env.PROXY_URL,
    token: `Basic ${token}`,
    connections: 2,
  });
  const response = await fetch(process.env.TARGET_URL || 'https://api.ipify.org?format=json', {
    dispatcher,
    redirect: 'manual',
    signal: AbortSignal.timeout(20_000),
  });
  console.log(`HTTP ${response.status}`);
  if (!response.ok) {
    await response.body?.cancel();
    process.exitCode = 1;
  } else {
    const body = await response.arrayBuffer();
    console.log(`Received ${body.byteLength} bytes`);
    try {
      const { ip } = JSON.parse(new TextDecoder().decode(body));
      if (typeof ip === 'string' && isIP(ip)) console.log(`Observed exit IP: ${ip}`);
    } catch { /* A non-JSON endpoint can still verify HTTP transport. */ }
  }
} catch (error) {
  // Do not log the raw error, request options or credential-bearing URLs.
  console.error(`Request failed: ${error.name}`);
  process.exitCode = 1;
} finally {
  await dispatcher?.close();
}

Save the complete example in this directory as node-fetch-proxy.mjs, then run node node-fetch-proxy.mjs. The .mjs extension selects ES modules without changing package.json. Success reports HTTP 200, a byte count and the returned exit IP.

The token is proxy-specific Basic authentication. Encoding it with Base64 does not encrypt the hop to the proxy. If you require TLS to the gateway itself, use a listener that explicitly supports it and configure its certificate trust. HTTPS to the destination remains a separate TLS connection. ProxyAgent documents those options.

The script disables redirects, aborts after 20 seconds, rejects non-2xx responses and releases the dispatcher. It reads a small diagnostic body into memory. For large exports, stream with a byte limit rather than substituting a large target URL into this diagnostic.

Recognize a dispatcher mismatch before changing credentials

We reproduced a specific dependency failure while developing the example: Node.js 22.23.1 built-in fetch paired with ProxyAgent from Undici 8.12.1 failed before the request reached the proxy. The nested error was invalid onRequestStart method. Importing both fetch and ProxyAgent from the same Undici installation passed the transport checks.

If you see this failure, capture the Node version and npm dependency tree first. Replacing the password, rotating the mobile IP or allowing another source address cannot repair an incompatible client dispatch interface.

This observation is specific to that version pair. It does not mean that every external dispatcher is incompatible with built-in fetch. Importing both functions from one package makes the fetch and dispatcher versions easier to check together. A framework can bundle another Undici version, so verify which fetch function the tool actually calls.

Use EnvHttpProxyAgent when the package owns environment routing

EnvHttpProxyAgent reads proxy and bypass variables for Undici requests. It is useful when your package-level client needs that behavior without making native Node environment support the routing owner. Constructing the agent alone does not route anything; attach it to the request.

javascript
import { fetch, EnvHttpProxyAgent } from 'undici';
const dispatcher = new EnvHttpProxyAgent();
try {
  const response = await fetch('https://api.ipify.org?format=json', {
    dispatcher,
    signal: AbortSignal.timeout(20_000),
    redirect: 'manual',
  });
  console.log(response.status);
  await response.body?.cancel();
} finally {
  await dispatcher.close();
}

This is a source-reviewed configuration sketch. The downloaded explicit ProxyAgent script and native environment mode are the lab-tested paths. The agent documentation describes precedence when lowercase and uppercase proxy variables coexist; avoid configuring competing values and hoping one wins.

In a service, create a reusable dispatcher for the intended integration, close it during shutdown, and limit the work queue feeding it. A connection count does not bound the number of promises your application can create. For account workflows, keep cookie handling and proxy session ownership together in the application layer; fetch does not become a browser merely because the exit IP is mobile.

Separate transport failures from HTTP responses

A rejected fetch promise often points to a connection, TLS or dispatcher problem. A resolved response with status 403 or 429 is still an HTTP response. Check response.ok before treating the operation as successful, and release or consume an unused body.

The complete script prints the top-level error name without serializing credential-bearing request options. In a private diagnostic environment, inspect the nested error type or code after redaction. Use the observed stage to decide what to change.

Node.js proxy diagnosis
ObservationLikely boundaryNext useful check
invalid onRequestStart methodFetch / dispatcher compatibilityCompare Node and Undici versions; use matching package imports.
407 during CONNECTGateway authenticationVerify proxy credentials or required source authorization.
Certificate verification failureTLS trust or hostnameUse the correct hostname and trusted CA; retain verification.
Abort or timeoutRequest deadline or cancellationTest a small endpoint, then inspect destination latency and queued work.
HTTP 403 / 429Destination applicationCheck permissions or delay policy; do not rotate and immediately retry.
Unexpected observed IPRouting selection or bypassInspect NO_PROXY and the actual fetch/dispatcher used by the worker.

Pass the dispatcher to the tool implementation

For an MCP server or retrieval worker, put the configured fetch wrapper in the code that performs the HTTP request. Keep the proxy secret in server configuration, and expose only the destination inputs the tool needs. A prompt instruction to use a proxy does not modify Node's network stack.

If the worker launches Playwright, use Playwright's proxy configuration for that browser. If it runs in another cloud region, verify the source address used for gateway allowlisting from that region.

For mobile proxy integrations, match session behavior to the task. A web scraping worker may have different continuity requirements from a one-off check against a US endpoint. Measure the actual received exit and compare target behavior before scaling up.

Inspect and reproduce the test evidence

The scripts were rerun on October 15, 2026 with Python 3.12.14, HTTPX 0.28.1, aiohttp 3.14.5, Node.js 22.23.1 and Undici 8.12.1. The lab runs an authenticated proxy and two origins on loopback. It checks the origin request count, missing proxy credentials at the origin, process exit status and reported output.

There are seven checks for each of the three clients, plus two checks for native Node environment routing. Download the lab ZIP, follow its README, and compare the recorded JSON results. The IP 203.0.113.42 is a documentation address returned by the fixture; it is not a Coronium exit or a measured location.

These are transport tests. They do not measure carrier speed, geographic coverage or success against a particular website. For a purchased port, repeat the single-request example from the machine running your job, then test the authorized destination and session lifetime you need.

Checks you can repeat with the downloadable lab
CheckObserved resultWhat it verifies
Authenticated HTTP and HTTPS CONNECTEach reaches the local origin onceProxy transport works with credentials containing reserved characters.
JSON IP responseThe script prints 203.0.113.42The diagnostic reads the returned IP, rather than guessing from the gateway.
Wrong proxy passwordNonzero exit; origin never reachedAuthentication failure cannot silently fall back to a direct request.
Untrusted TLS certificateNonzero exit; origin never reachedCertificate verification stays enabled.
HTTP 302 redirect302 reported; redirect not followed; nonzero exitThe first response remains visible for diagnosis.
HTTP 429 rate limitOne origin request; nonzero exitThe sample does not immediately retry or rotate.

Sources and review scope

Sources reviewed October 15, 2026. This guide reviews primary documentation. Code examples illustrate configuration and error handling. Any local fixture checks are described in the article; they are not live-provider performance benchmarks or guarantees of destination access.

Frequently asked questions

Configure another runtime

Use the settings supported by the process making the request, then verify routing and authentication.

Related workflows

Mobile proxies for web scraping

Match an authorized collector to its network and session requirements.

US mobile proxy options

Compare available carrier plans when your integration needs a US mobile exit.

HTTPX for Python workers

Configure the Python client separately in a mixed-runtime application.

Proxy IP allowlisting

Identify the worker address presented to the gateway.

Where to get a dedicated line

A Coronium mobile proxy is one physical device with its own SIM, rented to one customer. It connects over HTTP or SOCKS5, the IP changes by dashboard button, API link or timer, and data is not metered on dedicated lines. Brazil lines are the exception: 20 GB of data a month and a new IP on request only, with no timer. Stock and prices differ by country and carrier.