SOCKS Proxy HTTP/HTTPS Agent

Common errors

• Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/socks-proxy-agent/dist/index.js from ... not supported.

  cause Attempting to `require()` `socks-proxy-agent` in a CommonJS context when the library is ESM-only since v7.0.0.
  fix Change your import statement to `import { SocksProxyAgent } from 'socks-proxy-agent';` and ensure your project is configured for ES Modules (e.g., `"type": "module"` in `package.json`).

• TypeError: The agent option must be an Agent object, got [object Object]

  cause Instantiating `SocksProxyAgent` without the `new` keyword, or passing an incorrectly configured object as an agent.
  fix Ensure you are instantiating the class correctly: `const agent = new SocksProxyAgent(proxyUri);`

• Error: SOCKS proxy connection failed: Authentication failed

  cause The SOCKS proxy server rejected the provided username/password credentials, or they were not properly URL-encoded.
  fix Verify that the username and password in your SOCKS proxy URI are correct and properly URL-encoded (e.g., `user%40domain.com` for `user@domain.com`).

• Error: getaddrinfo ENOTFOUND proxy.example.com

  cause The hostname of the SOCKS proxy server could not be resolved by DNS.
  fix Check the proxy server hostname for typos. Ensure your system's DNS settings are correct, or that the proxy hostname is reachable. This can also happen if `socks5://` is used and the proxy expects `socks5h://` for remote DNS resolution.

Warnings

• breaking Version 10.0.0 increased the minimum Node.js version requirement to 20. Projects running on older Node.js versions will need to upgrade their runtime or stick to an earlier `socks-proxy-agent` version.
  Fix: Ensure your project runs on Node.js 20 or newer. If not possible, use `socks-proxy-agent@9.x.x` which supports Node.js 16+.
• breaking Starting with `socks-proxy-agent@7.0.0` (as part of the `proxy-agents` monorepo v7), the package is ESM-only. CommonJS `require()` statements will no longer work directly.
  Fix: Migrate your project to use ES Modules (`import`/`export` syntax) or configure your build system (e.g., Webpack, Rollup) to handle ESM. For testing, `node --experimental-modules` might be needed in older Node.js versions.
• gotcha Proxy authentication (username and password) must be included directly within the SOCKS proxy URI and URL-encoded if special characters are present. Incorrect encoding or format will lead to authentication failures.
  Fix: Format your proxy URI as `socks://username:password@host:port`. Ensure `username` and `password` are `encodeURIComponent()`-ed if they contain characters like `@`, `:`, `/`, etc.
• gotcha When using `socks-proxy-agent` with the `ws` (WebSocket) library, the `agent` option must be passed explicitly to the `WebSocket` constructor. This is a common oversight leading to direct connections instead of proxied ones.
  Fix: Pass the `agent` instance in the options object: `new WebSocket('ws://...', { agent: yourSocksProxyAgentInstance });`
• gotcha The `SocksProxyAgent` expects a SOCKS URI (e.g., `socks://`, `socks4://`, `socks5://`). Providing an HTTP/HTTPS proxy URI (e.g., `http://`) will result in incorrect behavior or errors as it's designed specifically for SOCKS protocols.
  Fix: Ensure the proxy URI starts with a valid SOCKS scheme (e.g., `socks://`, `socks5h://`). If you need to handle multiple proxy types dynamically, consider using the `proxy-agent` package from the same monorepo, which automatically detects the protocol.

Install

• npm install socks-proxy-agent npm
• yarn add socks-proxy-agent yarn
• pnpm add socks-proxy-agent pnpm

Imports

• SocksProxyAgent
  wrong:

  const SocksProxyAgent = require('socks-proxy-agent').SocksProxyAgent;

  correct:

  import { SocksProxyAgent } from 'socks-proxy-agent';

  Since v7.0.0 (proxy-agents monorepo), all packages are ESM-only, requiring `import` syntax. The class is a named export.
• SocksProxyAgentOptions
  wrong:

  import { SocksProxyAgentOptions } from 'socks-proxy-agent';

  correct:

  import type { SocksProxyAgentOptions } from 'socks-proxy-agent';

  Import types using `import type` for clarity and to avoid runtime issues in some bundlers/environments. This is a named export.
• Agent
  wrong:

  const agent = SocksProxyAgent(proxyUri);

  correct:

  import https from 'https'; // or http
  const agent = new SocksProxyAgent(proxyUri);

  The `SocksProxyAgent` is a class and must be instantiated with `new`.

Quickstart

Demonstrates how to create a `SocksProxyAgent` instance and use it with Node.js's built-in `https` module to route an HTTPS request through a SOCKS proxy, including basic error handling.

import https from 'https';
import { SocksProxyAgent } from 'socks-proxy-agent';

// Replace with your SOCKS proxy URI, including optional authentication
// Example with username/password: 'socks://user%40example.com:password@proxy.example.com:1080'
const SOCKS_PROXY_URI = process.env.SOCKS_PROXY_URI ?? 'socks://127.0.0.1:1080';

// Create a new SocksProxyAgent instance
const agent = new SocksProxyAgent(SOCKS_PROXY_URI);

console.log(`Making HTTPS request through SOCKS proxy: ${SOCKS_PROXY_URI}`);

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

  let data = '';
  res.on('data', (chunk) => {
    data += chunk;
  });
  res.on('end', () => {
    console.log('Response Body:');
    try {
      const json = JSON.parse(data);
      console.log(json);
    } catch (e) {
      console.error('Failed to parse JSON response:', e);
      console.log(data);
    }
  });
}).on('error', (err) => {
  console.error('Error making HTTPS request:', err.message);
});