HTTPS Proxy Agent

9.0.0 · active · verified Tue Apr 21

https-proxy-agent is an `http.Agent` implementation specifically designed for making HTTPS requests through an HTTP or HTTPS proxy server. It leverages the HTTP `CONNECT` method to establish a TCP tunnel through the proxy to the target destination. This enables secure communication over proxied networks and is also compatible with protocols like WebSockets that utilize the `CONNECT` method for proxy tunneling. The current stable version is 9.0.0, released as part of the `proxy-agents` monorepo, which implies a release cadence tied to updates across the proxy agent family. A key differentiator is its direct focus on the `CONNECT` method for HTTPS and WebSocket tunneling, providing a robust solution for environments requiring explicit proxy configuration. It requires Node.js version 20 or higher.

Common errors

```
Error [ERR_REQUIRE_ESM]: require() of ES module .../node_modules/https-proxy-agent/dist/index.mjs from .../my-app.js not supported.
```
cause Attempting to use `require()` to import `https-proxy-agent` when your project is configured for CommonJS, but the package is primarily ESM.

fix Convert your project to use ES Modules, or if that's not feasible, ensure your tooling (e.g., Webpack, Rollup) correctly handles ESM modules in a CommonJS context. The recommended fix is to use `import { HttpsProxyAgent } from 'https-proxy-agent';` and ensure your project's `type` is set to `module` in `package.json` or use an `.mjs` extension for your file.
```
Error: read ECONNRESET
```
cause This error often indicates that the proxy server closed the connection unexpectedly, possibly due to invalid credentials, incorrect proxy configuration, or network issues between your application and the proxy.

fix Double-check your proxy URL, port, and any required authentication. Verify network connectivity to the proxy server. The proxy might also be blocking the target URL.

Warnings

breaking Version 9.0.0 and above now require Node.js version 20 or higher. Older Node.js versions are no longer supported.
Fix: Upgrade your Node.js environment to version 20 or newer. If you cannot upgrade, use a previous major version of `https-proxy-agent` (e.g., `^8.0.0`).
gotcha When migrating from older versions or CommonJS, ensure you use ESM `import` syntax as the package's `package.json` `exports` field prioritizes ESM, potentially causing issues with `require()`.
Fix: Use `import { HttpsProxyAgent } from 'https-proxy-agent';` instead of `const HttpsProxyAgent = require('https-proxy-agent').HttpsProxyAgent;` in your JavaScript/TypeScript files.
gotcha The `proxy` argument to `HttpsProxyAgent` expects a URL string or `URL` object. Incorrectly formatted URLs or missing protocol can lead to connection errors.
Fix: Ensure the proxy URL is a valid string (e.g., 'http://proxy.example.com:8080' or 'https://secureproxy.com') or a `URL` object. Always include the protocol (http/https).

Install

npm install https-proxy-agent npm
yarn add https-proxy-agent yarn
pnpm add https-proxy-agent pnpm

Imports

HttpsProxyAgent
wrong:
```
const HttpsProxyAgent = require('https-proxy-agent').HttpsProxyAgent;
```
correct:
```
import { HttpsProxyAgent } from 'https-proxy-agent';
```
The package is primarily designed for ESM usage since v9.0.0. While CommonJS might work with transpilers, direct `require` can be problematic due to how `exports` are configured. Use named import from the package root.
HttpsProxyAgentOptions
wrong:
```
import { HttpsProxyAgentOptions } from 'https-proxy-agent';
```
correct:
```
import type { HttpsProxyAgentOptions } from 'https-proxy-agent';
```
When importing types for TypeScript, use `import type` to ensure they are stripped during compilation.

Quickstart

This quickstart demonstrates how to configure and use `HttpsProxyAgent` with Node.js's built-in `https` module to route requests through a specified HTTP(s) proxy server.

import * as https from 'https';
import { HttpsProxyAgent } from 'https-proxy-agent';

const PROXY_URL = process.env.HTTPS_PROXY ?? 'http://168.63.76.32:3128'; // Example proxy, replace with a real one
const TARGET_URL = 'https://example.com';

console.log(`Attempting to fetch ${TARGET_URL} via proxy ${PROXY_URL}`);

const agent = new HttpsProxyAgent(PROXY_URL, {
  headers: {
    'X-Custom-Proxy-Header': 'MyValue'
  }
});

https.get(TARGET_URL, { agent }, (res) => {
  console.log(`Status Code: ${res.statusCode}`);
  console.log('Response Headers:', res.headers);

  let data = '';
  res.on('data', (chunk) => {
    data += chunk;
  });
  res.on('end', () => {
    console.log('Response Body Snippet:', data.substring(0, 200) + '...');
  });
}).on('error', (err) => {
  console.error('Error fetching URL:', err.message);
});

view raw JSON →