{"id":16082,"library":"https-proxy-agent","title":"HTTPS Proxy Agent","description":"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.","status":"active","version":"9.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/TooTallNate/proxy-agents","tags":["javascript","https","proxy","endpoint","agent"],"install":[{"cmd":"npm install https-proxy-agent","lang":"bash","label":"npm"},{"cmd":"yarn add https-proxy-agent","lang":"bash","label":"yarn"},{"cmd":"pnpm add https-proxy-agent","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core abstract agent implementation extended by HttpsProxyAgent.","package":"agent-base","optional":false}],"imports":[{"note":"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.","wrong":"const HttpsProxyAgent = require('https-proxy-agent').HttpsProxyAgent;","symbol":"HttpsProxyAgent","correct":"import { HttpsProxyAgent } from 'https-proxy-agent';"},{"note":"When importing types for TypeScript, use `import type` to ensure they are stripped during compilation.","wrong":"import { HttpsProxyAgentOptions } from 'https-proxy-agent';","symbol":"HttpsProxyAgentOptions","correct":"import type { HttpsProxyAgentOptions } from 'https-proxy-agent';"}],"quickstart":{"code":"import * as https from 'https';\nimport { HttpsProxyAgent } from 'https-proxy-agent';\n\nconst PROXY_URL = process.env.HTTPS_PROXY ?? 'http://168.63.76.32:3128'; // Example proxy, replace with a real one\nconst TARGET_URL = 'https://example.com';\n\nconsole.log(`Attempting to fetch ${TARGET_URL} via proxy ${PROXY_URL}`);\n\nconst agent = new HttpsProxyAgent(PROXY_URL, {\n  headers: {\n    'X-Custom-Proxy-Header': 'MyValue'\n  }\n});\n\nhttps.get(TARGET_URL, { agent }, (res) => {\n  console.log(`Status Code: ${res.statusCode}`);\n  console.log('Response Headers:', res.headers);\n\n  let data = '';\n  res.on('data', (chunk) => {\n    data += chunk;\n  });\n  res.on('end', () => {\n    console.log('Response Body Snippet:', data.substring(0, 200) + '...');\n  });\n}).on('error', (err) => {\n  console.error('Error fetching URL:', err.message);\n});\n","lang":"typescript","description":"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."},"warnings":[{"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`).","message":"Version 9.0.0 and above now require Node.js version 20 or higher. Older Node.js versions are no longer supported.","severity":"breaking","affected_versions":">=9.0.0"},{"fix":"Use `import { HttpsProxyAgent } from 'https-proxy-agent';` instead of `const HttpsProxyAgent = require('https-proxy-agent').HttpsProxyAgent;` in your JavaScript/TypeScript files.","message":"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()`.","severity":"gotcha","affected_versions":">=9.0.0"},{"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).","message":"The `proxy` argument to `HttpsProxyAgent` expects a URL string or `URL` object. Incorrectly formatted URLs or missing protocol can lead to connection errors.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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.","cause":"Attempting to use `require()` to import `https-proxy-agent` when your project is configured for CommonJS, but the package is primarily ESM.","error":"Error [ERR_REQUIRE_ESM]: require() of ES module .../node_modules/https-proxy-agent/dist/index.mjs from .../my-app.js not supported."},{"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.","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.","error":"Error: read ECONNRESET"}],"ecosystem":"npm"}