How to send requests through a proxy in Node.js (fetch and axios)

What you need

The proxy is issued in the format host:port:login:password. Replace HOST, PORT, LOGIN and PASSWORD in the examples with your own values. Node.js 20 or newer is required; the examples are written as ES modules (a file with the .mjs extension).

The built-in fetch does not use a proxy by itself. To route it through a proxy you need ProxyAgent from the undici package, and for compatibility fetch is taken from the same package.

npm install undici axios

Example

import { fetch, ProxyAgent } from "undici";

const HOST = "HOST";
const PORT = "PORT";
const LOGIN = "LOGIN";
const PASSWORD = "PASSWORD";

// We build the Proxy-Authorization header ourselves: this way special characters need no encoding
const token = "Basic " + Buffer.from(LOGIN + ":" + PASSWORD).toString("base64");

// The proxy scheme is http:// even for HTTPS sites
const dispatcher = new ProxyAgent({ uri: "http://" + HOST + ":" + PORT, token });

// AbortSignal.timeout limits the request time so it does not hang
const response = await fetch("https://api.ipify.org", {
  dispatcher,
  signal: AbortSignal.timeout(30000),
});

// The service returns the address the request came from
console.log(await response.text());

import axios from "axios";

const response = await axios.get("https://api.ipify.org", {
  // axios sends the login and password in the Proxy-Authorization header
  proxy: {
    protocol: "http",
    host: "HOST",
    port: Number("PORT"),
    auth: { username: "LOGIN", password: "PASSWORD" },
  },
  timeout: 30000,
});

console.log(response.data);

If SOCKS5

undici has Socks5ProxyAgent, but its documentation marks it as experimental (it appeared in version 7.23.0) and it prints a warning when created. For axios there is no built-in SOCKS5 in the documentation. If you need stability, use the proxy's HTTP port.

import { fetch, Socks5ProxyAgent } from "undici";

// The credentials are passed as separate parameters, no need to encode them
const dispatcher = new Socks5ProxyAgent("socks5://HOST:SOCKS_PORT", {
  username: "LOGIN",
  password: "PASSWORD",
});

const response = await fetch("https://api.ipify.org", { dispatcher });
console.log(await response.text());

Common errors

1. 407 Proxy Authentication Required: the login or password is wrong. For undici, check that the token starts with the word Basic and a space.
2. Timeout or UND_ERR_CONNECT_TIMEOUT: check HOST and PORT and whether the SOCKS5 port was put into HTTP mode.
3. Special characters in the password: in the ways shown in this guide the password is passed separately and needs no encoding. If you write the login and password in the address (http://LOGIN:PASSWORD@HOST:PORT), encode each value with encodeURIComponent.
4. The https:// scheme in the proxy address: the issued proxy works over HTTP, so write http://HOST:PORT both in the uri for undici and in protocol for axios.
5. Calling the built-in fetch with a dispatcher from the undici package may fail because of a version mismatch. Import fetch from undici, as in the example.
6. Old versions of axios handle HTTPS through a proxy poorly. Update to a current version.