skip to content

How do you make a Node 24 service send its fetch() and http.request() calls through the proxy named in HTTP_PROXY and HTTPS_PROXY?

level: middleimportance: should knowfreq 30%

answer

  1. ignored unless you opt in
  2. an environment variable or a flag
  3. global agent and global dispatcher
  4. custom agents need proxyEnv

basics

~20 s

Node ignores HTTP_PROXY and HTTPS_PROXY unless you opt in with NODE_USE_ENV_PROXY=1 or --use-env-proxy. Node 24 then routes fetch() and the global http and https agents through the proxy, honouring NO_PROXY; custom agents need a proxyEnv option.

solid answer

~40 s

By default Node reads no proxy variables at all. Setting `NODE_USE_ENV_PROXY=1` (fetch support since v24.0.0) or passing `--use-env-proxy` (v24.5.0) makes Node parse `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` at startup: it installs undici's `EnvHttpProxyAgent` as the global dispatcher for `fetch()`, and builds `http.globalAgent` and `https.globalAgent` with `proxyEnv: process.env` (supported for `node:http` and `node:https` since v24.5.0). Lowercase names win over uppercase ones. A request that passes its own `agent`, or a library that installs its own global dispatcher, bypasses this, so give custom agents `proxyEnv`. `http.setGlobalProxyFromEnv()` (v24.14.0) does the same at runtime and returns a restore function; call it before any requests. The feature is marked Stability 1.1, active development.

code

bash · 6 lines
bash
HTTPS_PROXY=http://proxy.internal:8080 \
NO_PROXY=localhost,127.0.0.1,.internal \
NODE_USE_ENV_PROXY=1 node server.js

# or, from v24.5.0, the flag form
HTTPS_PROXY=http://proxy.internal:8080 NO_PROXY=.internal node --use-env-proxy server.js

go deeper

for a junior

Recall that Node does not read HTTP_PROXY by default and that NODE_USE_ENV_PROXY=1 or --use-env-proxy turns it on.

for a middle

Explain which clients the switch covers in Node 24, how NO_PROXY bypasses work, and why a custom agent needs proxyEnv.

for a senior

Trace why one call skips the proxy: an explicit agent, a replaced global dispatcher or a NO_PROXY match, and fix it at the right layer.

for a principal

Decide whether proxy configuration lives in deployment environment, in code via setGlobalProxyFromEnv(), or in a shared client wrapper.

## The default: no proxy at all Many tools read `HTTP_PROXY` and friends automatically. Node does **not**. Out of the box, `fetch()`, `http.request()` and `https.request()` connect directly to the target, so a service deployed behind a mandatory egress proxy fails with connection errors even though the variables are set in its environment. ## Opting in for the whole process Node 24 offers two equivalent switches: - **`NODE_USE_ENV_PROXY=1`**, an environment variable (added in v24.0.0, when it covered `fetch()`). - **`--use-env-proxy`**, a command-line flag (added in v24.5.0). When both are set, the flag takes precedence. The Node guide on enterprise networks records the coverage: `fetch()` from v24.0.0, `node:http` and `node:https` methods from v24.5.0. With either switch on and at least one proxy variable present, Node at startup: 1. installs undici's **`EnvHttpProxyAgent`** as the global dispatcher, which `fetch()` uses; 2. constructs `http.globalAgent` and `https.globalAgent` with **`proxyEnv: process.env`**, so `http.request()` without an explicit agent goes through the proxy. The variables read are: | Variable | Used for | |---|---| | `HTTP_PROXY` / `http_proxy` | proxy URL for `http:` targets | | `HTTPS_PROXY` / `https_proxy` | proxy URL for `https:` targets | | `NO_PROXY` / `no_proxy` | targets that bypass the proxy | When both spellings are set, the **lowercase** one wins. Proxy URLs may be `http://` or `https://` and may carry credentials as `http://user:password@host:port`. Requests to a Unix domain socket ignore proxy settings. ## NO_PROXY for internal services A service that calls an external payment API through the proxy and an internal inventory API directly needs `NO_PROXY`. Node accepts: - `*` to bypass everything; - an exact host (`inventory.internal`), a suffix (`.internal`) or a wildcard (`*.internal`); - an exact IP or an IP range such as `10.0.0.1-10.0.0.255`; - a host with a port, such as `inventory.internal:8080`. Entries are comma-separated. ## Where the global switch does not reach - **Custom `http.Agent` / `https.Agent` instances.** A request that passes its own `agent` uses that agent's settings. Since v24.5.0 the constructor accepts **`proxyEnv`**, either `process.env` or an object with explicit `HTTP_PROXY`, `HTTPS_PROXY` and `NO_PROXY` values. - **A replaced global dispatcher.** A library that calls `setGlobalDispatcher()` with its own dispatcher replaces the proxy-aware one for `fetch()`. - **A per-call `dispatcher`.** Passing a dispatcher to `fetch()` overrides the global one for that call; undici's `ProxyAgent` is the programmatic option there. ## Turning it on at runtime `http.setGlobalProxyFromEnv([proxyEnv])`, added in **v24.14.0**, enables the same support for `fetch()`, `http.request()` and `https.request()` from code. It defaults to `process.env`, overrides whatever `http.globalAgent`, `https.globalAgent` or the global dispatcher were before, and **returns a function that restores the previous state**. The docs advise calling it before any requests are made, not in the middle of traffic. ## Which setting wins Proxy decisions resolve from the most specific setting to the least: 1. A per-call `dispatcher` passed to `fetch()`, or an explicit `agent` passed to `http.request()`, decides for that call. 2. Otherwise the current global dispatcher (for `fetch()`) or global agent (for `node:http` and `node:https`) decides, including one a library or `http.setGlobalProxyFromEnv()` installed. 3. Otherwise the startup configuration applies, which exists only if the switch was on **and** at least one of `HTTP_PROXY`, `HTTPS_PROXY`, `http_proxy` or `https_proxy` was set; with none of them set, nothing is proxied. Within a proxy-aware client, a target matching `NO_PROXY` connects directly. The switch can also arrive indirectly: `--use-env-proxy` is allowed in `NODE_OPTIONS`, and the Node guide shows `NODE_USE_ENV_PROXY=1` loaded from an env file through `--env-file`. ## A worked setup For a service that calls an external payment API and an internal inventory API: 1. Set `HTTPS_PROXY` to the egress proxy, so `https:` calls to the payment API go through it. 2. Set `NO_PROXY=localhost,127.0.0.1,.internal`, so the inventory API under `.internal` and local health checks connect directly. 3. Set `NODE_USE_ENV_PROXY=1` in the deployment configuration, not in code. 4. Give any custom `https.Agent` built for the payment API `proxyEnv: process.env`, or it will try to connect directly and fail at the firewall. ## Operational notes - The feature is marked **Stability 1.1, active development**, so check the release notes when upgrading. - The docs warn that the proxy is a trusted party: it sees connection metadata, and full contents for plain HTTP or when it terminates TLS. Configure only proxies authorised for the deployment. - A proxy that intercepts TLS presents its own certificate authority; trusting it is a TLS configuration step, covered with Node's TLS options.

  • NODE_USE_ENV_PROXY=1 is set, but one http.request() call still goes direct. What is the likely cause?
    That call passes its own `agent`, which does not inherit the global agent's proxy settings. Create the agent with `proxyEnv: process.env` (supported since v24.5.0) or an explicit `proxyEnv` object, or let the request use `http.globalAgent`. Also check whether the host matches an entry in `NO_PROXY` or `no_proxy`, which wins over the proxy.
  • When would you use http.setGlobalProxyFromEnv() instead of the environment switch?
    When proxy settings are only known at runtime, for example read from a secrets store, or when tests need to enable and then undo proxying. Available since v24.14.0, it configures `fetch()` and the global agents together and returns a restore function. Call it before traffic starts, because it replaces the global agents and dispatcher.

  • Node honours HTTP_PROXY automatically, like most command-line tools.
  • Setting http.globalAgent to a proxy-aware agent also proxies fetch.
  • A custom http.Agent inherits proxy settings from NODE_USE_ENV_PROXY.
  • Uppercase HTTP_PROXY wins when both spellings are set.
  • Proxying fetch in Node always requires installing a third-party package.

Assumes Node 24: NODE_USE_ENV_PROXY covers fetch() since v24.0.0, --use-env-proxy and proxy support for node:http and node:https arrived in v24.5.0, and http.setGlobalProxyFromEnv() in v24.14.0.