Node.js Fetch Proxy Setup: Environment and Auth
Configure Node fetch with proxy environment support and authenticated URLs. Check version requirements, global settings and NO_PROXY with tested examples.
By Proxies.sx Team. Reviewed .
On the tested Node.js 24.16 runtime, enable environment proxy support at startup or call http.setGlobalProxyFromEnv before making requests. Setting HTTP_PROXY alone did not route fetch through the proxy in our local test.
In this guide
Configure the process before calling fetch
This complete example uses http.setGlobalProxyFromEnv, available from Node 24.14. It was tested on Node 24.16.0 and needs no npm dependency. Check node --version inside the process or container you actually deploy.
Supply PROXY_SERVER, PROXY_USERNAME and PROXY_PASSWORD using the shared configuration inputs. The program encodes each raw credential once, including literal percent signs. Leave NO_PROXY empty when you intend the sample target to use the proxy.
// Node.js 24.14+; tested with Node.js 24.16.0.
import { setGlobalProxyFromEnv } from 'node:http';
const proxy = new URL(process.env.PROXY_SERVER);
// Encode each raw credential once, including literal percent signs.
proxy.username = encodeURIComponent(process.env.PROXY_USERNAME);
proxy.password = encodeURIComponent(process.env.PROXY_PASSWORD);
// This changes the process-wide default HTTP agents and fetch dispatcher.
const restore = setGlobalProxyFromEnv({
http_proxy: proxy.href,
https_proxy: proxy.href,
no_proxy: process.env.NO_PROXY ?? '',
});
try {
const response = await fetch(
process.env.TARGET_URL ?? 'https://api.ipify.org?format=json',
{ signal: AbortSignal.timeout(15000), redirect: 'error' },
);
if (!response.ok) throw new Error(`Destination returned HTTP ${response.status}`);
console.log(await response.json());
} catch (error) {
console.error('Request failed:', error.name);
process.exitCode = 1;
} finally {
restore();
}
Use the startup switch for an environment-managed process
If your deployment already supplies proxy URLs, you can enable environment support before the application starts. The environment should contain the appropriate HTTP_PROXY, HTTPS_PROXY and optional NO_PROXY values. Credentials inside those URLs must be encoded.
Run the command below with a supported runtime and your own entry file. The versioned command-line reference documents the switch and NODE_USE_ENV_PROXY=1 alternative. We tested this path on 24.16.0; do not assume every older Node binary accepts the flag.
node --version
node --use-env-proxy app.mjs
# Alternative startup opt-in:
NODE_USE_ENV_PROXY=1 node app.mjsUnderstand the process-wide effect
setGlobalProxyFromEnv replaces global HTTP agent and fetch dispatcher configuration. It can affect other requests in the process that use those defaults. The returned function restores the prior configuration; our single-request example calls it after consuming the response.
Configure a long-running worker at startup, before it serves concurrent work. Do not switch the global proxy around individual concurrent jobs. A library that supplies its own dispatcher or HTTP agent may use a different route. Node documents this scope in the global proxy API.
If you need a separate proxy per request, review the dispatcher API for the specific installed Undici version. Check that package's Node version requirements before installing it. The dependency-free example on this page intentionally uses Node's process-wide API.
What the local proxy actually observed
We ran the same built-in fetch request against a local target with proxy environment variables present. Without opt-in, it went directly to the target. With --use-env-proxy, the fixture recorded a CONNECT tunnel. An exact NO_PROXY match bypassed the proxy again.
The explicit example also completed an authenticated tunnel to a local HTTPS origin and failed when given the wrong proxy password. Its certificate check used a locally trusted fixture CA. These are routing observations for Node 24.16.0, not a claim about every Node release or public proxy.
See the recorded checks and cross-client environment table. Counting proxy connections in the fixture gives a stronger routing check than treating any successful HTTP response as proof that a proxy was used.
Diagnose the failing layer
| Symptom | Check |
|---|---|
| Unknown startup option or missing setGlobalProxyFromEnv export | Inspect the deployed Node version and use an API it supports. |
| Proxy variables exist but the target is reached directly | Check opt-in, NO_PROXY, lowercase duplicates and custom dispatchers. |
| URIError while reading proxy credentials | Encode raw URL credentials once. A literal percent sign needs %25. |
| fetch failed | Inspect a sanitized error cause locally to distinguish CONNECT, TLS, DNS and timeout failures. |
The sample prints only the error name to avoid exposing a complete proxy URL. A support report can add the cause code and UTC time after removing credentials. For a confirmed proxy authentication challenge, use the 407 guide.
Once a single request works, check your intended destination and payload. Then use the concurrency measurement guide before increasing load.
Common questions
Does fetch have a proxy option like Axios?
This example configures Node’s global dispatcher before calling fetch. It does not pass an Axios-style proxy object to fetch; the configuration belongs to Node’s documented proxy API.
Does this configure browser fetch too?
No. This example runs in Node.js. JavaScript executing in a web page uses the browser’s networking environment and does not gain these Node APIs.
Is this the node-fetch npm package?
This guide uses fetch built into Node.js, with no import from node-fetch. If your application imports a separate fetch package, check that package’s proxy configuration and supported versions.
Sources and test scope
Official documentation checked on 14 October 2026. The linked local test records identify the tested versions and limits. The examples do not establish public proxy availability or destination acceptance.
- Node 24.16 global proxy API and built-in support
- Node 24.16 proxy startup switch
- Undici ProxyAgent reference
Machine-readable guide index and local routing test results.
Connect your application to Proxies.sx
Use the username builder for gateway routing fields and the format converter for existing connection lists. Review Pool Gateway documentation, then check current mobile stock before buying traffic.
For agent-driven workflows, the agent service index lists the supported APIs. A configured HTTP client still needs to validate its task's response.
Configure the client that sends your requests
Start with the proxy configuration guide, or open the setup for your runtime.