Handling Proxy Authentication in node-fetch: Tips and Tricks

When building web scraping or API request workflows in Node.js, proxy authentication is often required to maintain security and access control. node-fetch does not support proxies natively, but with the right setup you can authenticate and route requests through any proxy server reliably and securely.

Why Proxy Authentication Matters in node-fetch

Authenticated proxies ensure only authorised users can route traffic through the server. Without proper authentication handling, your requests will fail with a 407 error or be silently blocked. Understanding how to pass credentials correctly is the foundation of any stable proxy setup.

Setting Up Proxy Authentication with https-proxy-agent

Step 1: Install the Required Package

Since node-fetch has no built-in proxy support, install https-proxy-agent to handle authenticated connections:

npm install node-fetch https-proxy-agent

Step 2: Pass Credentials in the Proxy URL

The simplest method is to embed credentials directly in the proxy URL string and pass it to HttpsProxyAgent:

const fetch = require('node-fetch');
const { HttpsProxyAgent } = require('https-proxy-agent');

const proxyAgent = new HttpsProxyAgent(
  'http://username:password@proxy_host:port'
);

fetch('https://example.com', { agent: proxyAgent })
  .then(res => res.text())
  .then(console.log);

Step 3: Use Environment Variables for Security

Never hardcode credentials in your source code. Store them in a .env file and reference them via process.env:

const proxyUrl = `http://${process.env.PROXY_USER}:${process.env.PROXY_PASS}@proxy_host:port`;
const agent = new HttpsProxyAgent(proxyUrl);

fetch('https://example.com', { agent })
  .then(res => res.text())
  .then(console.log);

Tip: URL-Encode Special Characters in Credentials

If your username or password contains special characters like @, :, or #, URL-encode them before inserting into the proxy string to avoid parsing errors.

Common Authentication Issues and How to Fix Them

Incorrect Credentials Format

The most frequent cause of auth failure is a malformed proxy URL. Double-check your .env file for typos, extra spaces, or missing port numbers. For more debugging strategies, read our guide on debugging common proxy issues in node-fetch.

Using SOCKS5 Proxies

For SOCKS5 authenticated proxies, use socks-proxy-agent instead of https-proxy-agent:

npm install socks-proxy-agent

const { SocksProxyAgent } = require('socks-proxy-agent');
const agent = new SocksProxyAgent('socks5://username:password@proxy_host:port');

Best Practices for Secure Proxy Authentication

• Always use environment variables — never hardcode credentials.
• URL-encode special characters in usernames and passwords.
• Rotate proxies to avoid rate limiting and IP bans.
• Add error handling to catch 407 authentication errors gracefully.
• For a full proxy setup walkthrough, see our complete guidelines for using proxies with node-fetch.
• Need step-by-step config help? Check our step-by-step proxy configuration guide.

Frequently Asked Questions