Node.js Proxy Setup: Environment Variables, fetch, axios and SOCKS5

Built-in support through environment variables

The Node.js HTTP documentation describes built-in proxy support that reads the HTTP_PROXY, HTTPS_PROXY and NO_PROXY variables, in lower or upper case. It is off unless you turn it on with the NODE_USE_ENV_PROXY=1 variable or the --use-env-proxy flag, and the docs mark it Stability 1.1, active development. The NODE_USE_ENV_PROXY variable was added in v24.0.0 and v22.21.0, and the --use-env-proxy flag and the proxyEnv option of http.Agent in v24.5.0 and v22.21.0; older versions ignore the variable. When on, it applies to fetch() from v24.0.0 and v22.21.0, and to http.request() and https.request() through the global agent from v24.5.0 and v22.21.0, so on v24.0.0 to v24.4.x it covers fetch() only.

The documented proxy URL formats are http:// and https://, with credentials written as http://username:password@host:port. So this built-in support covers HTTP proxies; it does not cover SOCKS5.

Built-in support through environment variables: example

NODE_USE_ENV_PROXY=1 \
HTTPS_PROXY="http://USERNAME:[email protected]:2222" \
node app.js

Replace USERNAME and PASSWORD with the values from My assets. Use HTTP_PROXY too if you request plain http:// addresses. This needs Node.js v24.5.0 or v22.21.0 or newer for the http and https modules; fetch() honours it from v24.0.0 (v22.21.0 on Node 22).

Built-in support through environment variables, continued

The docs also describe http.setGlobalProxyFromEnv() (added in v24.14.0 and v25.4.0) to switch this on from code. Node.js says built-in proxy support is not an anonymity feature and that a proxy can see connection metadata, so use only proxies you trust.

• Sources:
• Node.js documentation: HTTP, Built-in Proxy Support
• Node.js documentation: command-line options, --use-env-proxy

fetch with undici ProxyAgent

Install the undici package and pass a ProxyAgent as the dispatcher. The current undici documentation says a ProxyAgent routes requests through an HTTP, HTTPS or SOCKS5 proxy (check that your installed undici version supports socks5: URLs; the example below uses the HTTP port), and that credentials in the proxy URL are URL-decoded before use.

fetch with undici ProxyAgent: example

import { ProxyAgent, fetch } from 'undici'

const user = encodeURIComponent('USERNAME')
const pass = encodeURIComponent('PASSWORD')
const dispatcher = new ProxyAgent(`http://${user}:${pass}@proxy.proxy302.com:2222`)

const res = await fetch('https://ipinfo.io/json', { dispatcher })
console.log(await res.json())

Encoding the password protects characters such as @, : and / that would otherwise break the URL.

• Sources:
• undici documentation: ProxyAgent
• MDN: encodeURIComponent()

axios

The axios documentation lets you set a proxy object with protocol, host, port and auth (username and password) on a request. For an https:// target, axios 1.16.1 and newer open a CONNECT tunnel through the proxy. In 1.16.0 and older the Node http adapter sends the request to an HTTP proxy as a plain-text forward-proxy request, with no tunnel and no end-to-end TLS, so update axios first (1.17.0 also keeps the TLS options of your own httpsAgent inside the tunnel). If the proxy itself uses HTTPS, set protocol to https; Proxy302's HTTP port 2222 takes protocol http.

axios: example

import axios from 'axios'

const res = await axios.get('https://ipinfo.io/json', {
  proxy: {
    protocol: 'http',
    host: 'proxy.proxy302.com',
    port: 2222,
    auth: { username: 'USERNAME', password: 'PASSWORD' },
  },
})
console.log(res.data)

In the proxy object the username and password are separate fields, so they are not URL-encoded.

• Sources:
• axios documentation: request config, proxy

Proxy agents, including SOCKS5

The proxy-agents project provides http.Agent classes for the built-in http and https modules. https-proxy-agent connects to an HTTP or HTTPS proxy and uses the CONNECT method. socks-proxy-agent connects to a SOCKS proxy. In the package source, both read the username and password from the proxy URL and URL-decode them, and socks-proxy-agent accepts the schemes socks4, socks4a, socks5 and socks5h.

Proxy agents, including SOCKS5: example

import https from 'node:https'
import { SocksProxyAgent } from 'socks-proxy-agent'

const agent = new SocksProxyAgent(
  `socks5h://${encodeURIComponent('USERNAME')}:${encodeURIComponent('PASSWORD')}@proxy.proxy302.com:3333`
)
https.get('https://ipinfo.io/json', { agent }, (res) => res.pipe(process.stdout))

With socks5h the proxy resolves the host name. Proxy302 SOCKS5 is on port 3333; for an HTTP proxy use HttpsProxyAgent with port 2222.

• Sources:
• proxy-agents project: https-proxy-agent and socks-proxy-agent

Check the exit

Request https://ipinfo.io/json through the proxy, as in each example above. The country and org fields should describe the proxy, not your own connection. If the result shows your own address, the request did not use the proxy: check that the variable was set before Node started, or that the agent or dispatcher is passed to this request. The proxy location guide explains the fields.

• proxy location guide

Typical errors

ECONNREFUSED means the target machine actively refused the connection, which the Node.js error list says usually results from no service being active there: check the host and the port. ETIMEDOUT means the other side did not respond in time: check the port, your network and the timeout you set. ENOTFOUND is a DNS lookup failure: check the host name. Status 407 means the proxy did not accept the credentials; see the authentication guide. Also check that the protocol matches the port, HTTP on 2222 and SOCKS5 on 3333; the connection failed guide walks through the checks.

• authentication guide
• connection failed guide

• Sources:
• Node.js documentation: common system errors

How to do it with Proxy302

Any of these clients only needs the host, port, username and password of a Proxy302 proxy. Rotating residential traffic is billed per GB and the exit country is set when you generate the proxy; HTTP is on port 2222 and SOCKS5 on port 3333 of proxy.proxy302.com. A static ISP IP stays fixed for the whole lease term and does not rotate. The table shows exits in 7 countries from our latest hourly check; the probe sends its request to ChatGPT, which is only an example target of a network check. A proxy does not change ChatGPT's terms, and OpenAI's list of supported countries still applies. Details are on the rotating residential page and in the proxy location guide.

• rotating residential page
• proxy location guide
• ChatGPT, Claude and Gemini supported countries

Measured exits: ChatGPT from 7 countries

Hourly check of the Proxy302 probe, 25 October 2026, 08:29 UTC: one request to ChatGPT per country through a dynamic residential exit, using the public Proxy302 entry. Only the first three octets of an IP are public. One sample per country, not an average; later checks will differ.

• Sources:
• Proxy302 hourly connectivity check

How to do it with Proxy302: steps

1. Step 1

   Open the rotating residential page, choose the line, and keep Protocol on HTTP or choose SOCKS5, then click Review cost and generate.

2. Step 2

   Open My assets (the console page that holds everything you bought) and copy HOST, PORT, USERNAME and PASSWORD. The Connect page shows a ready example with your own endpoint.

3. Step 3

   Enter the details in the browser or tool you are setting up.

4. Step 4

   Confirm the exit with https://ipinfo.io/json through the proxy.

5. Step 5

   From mainland China, start the helper tool from the Connect page first and keep it open while you use the proxy.

   • Helper tool guide

Prices and limits

The Budget line costs US$1.50 per GB, US$1.35 per GB in a 100 GB package and US$1.20 per GB at 300 GB. There is no free trial, and the smallest purchase is 1 GB. Which exit locations are available changes daily.

• Sources:
• Proxy302 product facts and price list

FAQ

Read next

Proxy address, port, username and password

Every working proxy is described by five basic fields: protocol, host address, port, login, and password.

407 Proxy Authentication Required

HTTP 407 Proxy Authentication Required comes from the proxy server, not from the website you are trying to reach.

Fix ERR_PROXY_CONNECTION_FAILED

The ERR_PROXY_CONNECTION_FAILED error appears in Chrome and Edge when the browser cannot establish a connection with a proxy server.

Check a proxy's IP, country and ISP

Check the exit IP, country and ISP your proxy really gives you in 30 seconds — and why IP databases disagree on the city. With our own test of three lookup services.