Registry / http-networking / socks-proxy-agent

socks-proxy-agent

library10.0.0jsnpmunverified

socks-proxy-agent is a Node.js module that provides an `http.Agent` implementation, enabling HTTP and HTTPS requests, and WebSocket connections, to be routed through a SOCKS proxy server. It supports SOCKS4, SOCKS4a, SOCKS5, and SOCKS5h protocols, offering flexibility in how connections are established and resolved. The current stable version is 10.0.0. The package is part of the broader `proxy-agents` monorepo by TooTallNate, which implies a release cadence often synchronized with its core dependency `agent-base` and Node.js LTS updates, as evidenced by the recent major version bump due to an increased minimum Node.js requirement. Its key differentiator is its focused and robust implementation for SOCKS proxies, making it suitable for scenarios requiring specific proxy tunneling capabilities for anonymity, bypassing geo-restrictions, or internal network access.

http-networking

npm install socks-proxy-agent

github ↗package ↗

INSTALL

IMPORT

SIG · SOCKS-PROXY-AGENT

socks-proxy-agent

http-networkingjavascriptv10.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

SocksProxyAgent

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

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

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

SocksProxyAgentOptions

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

✗ import { 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

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

✗ const agent = SocksProxyAgent(proxyUri);

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

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); });

Debug

Known issues

breakingVersion 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+.

affects: >=10.0.0

breakingStarting 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.

affects: >=7.0.0

gotchaProxy 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.

affects: >=1.0.0

gotchaWhen 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 });`

affects: >=1.0.0

gotchaThe `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.

affects: >=1.0.0

Errors

Common errors & fixes

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

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]

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

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

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.

Upgrade

Version history

10.0.0latest on npm

Audit

Dependencies

agent-baserequiredCore dependency providing the base `http.Agent` functionality that `SocksProxyAgent` extends.

socksrequiredProvides the underlying SOCKS protocol implementation and negotiation.

debugoptionalUsed for internal debugging output.

Agent activity

8 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/TooTallNate/proxy-agents ↗

packagehttps://www.npmjs.com/package/socks-proxy-agent ↗