{"id":16223,"library":"socks-proxy-agent","title":"SOCKS Proxy HTTP/HTTPS Agent","description":"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.","status":"active","version":"10.0.0","language":"javascript","source_language":"en","source_url":"https://github.com/TooTallNate/proxy-agents","tags":["javascript","agent","http","https","proxy","socks","socks4","socks4a","socks5"],"install":[{"cmd":"npm install socks-proxy-agent","lang":"bash","label":"npm"},{"cmd":"yarn add socks-proxy-agent","lang":"bash","label":"yarn"},{"cmd":"pnpm add socks-proxy-agent","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core dependency providing the base `http.Agent` functionality that `SocksProxyAgent` extends.","package":"agent-base","optional":false},{"reason":"Provides the underlying SOCKS protocol implementation and negotiation.","package":"socks","optional":false},{"reason":"Used for internal debugging output.","package":"debug","optional":true}],"imports":[{"note":"Since v7.0.0 (proxy-agents monorepo), all packages are ESM-only, requiring `import` syntax. The class is a named export.","wrong":"const SocksProxyAgent = require('socks-proxy-agent').SocksProxyAgent;","symbol":"SocksProxyAgent","correct":"import { SocksProxyAgent } from 'socks-proxy-agent';"},{"note":"Import types using `import type` for clarity and to avoid runtime issues in some bundlers/environments. This is a named export.","wrong":"import { SocksProxyAgentOptions } from 'socks-proxy-agent';","symbol":"SocksProxyAgentOptions","correct":"import type { SocksProxyAgentOptions } from 'socks-proxy-agent';"},{"note":"The `SocksProxyAgent` is a class and must be instantiated with `new`.","wrong":"const agent = SocksProxyAgent(proxyUri);","symbol":"Agent","correct":"import https from 'https'; // or http\nconst agent = new SocksProxyAgent(proxyUri);"}],"quickstart":{"code":"import https from 'https';\nimport { SocksProxyAgent } from 'socks-proxy-agent';\n\n// Replace with your SOCKS proxy URI, including optional authentication\n// Example with username/password: 'socks://user%40example.com:password@proxy.example.com:1080'\nconst SOCKS_PROXY_URI = process.env.SOCKS_PROXY_URI ?? 'socks://127.0.0.1:1080';\n\n// Create a new SocksProxyAgent instance\nconst agent = new SocksProxyAgent(SOCKS_PROXY_URI);\n\nconsole.log(`Making HTTPS request through SOCKS proxy: ${SOCKS_PROXY_URI}`);\n\nhttps.get('https://ipinfo.io/json', { agent }, (res) => {\n  console.log(`Response Status: ${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:');\n    try {\n      const json = JSON.parse(data);\n      console.log(json);\n    } catch (e) {\n      console.error('Failed to parse JSON response:', e);\n      console.log(data);\n    }\n  });\n}).on('error', (err) => {\n  console.error('Error making HTTPS request:', err.message);\n});","lang":"typescript","description":"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."},"warnings":[{"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+.","message":"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.","severity":"breaking","affected_versions":">=10.0.0"},{"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.","message":"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.","severity":"breaking","affected_versions":">=7.0.0"},{"fix":"Format your proxy URI as `socks://username:password@host:port`. Ensure `username` and `password` are `encodeURIComponent()`-ed if they contain characters like `@`, `:`, `/`, etc.","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Pass the `agent` instance in the options object: `new WebSocket('ws://...', { agent: yourSocksProxyAgentInstance });`","message":"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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"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.","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":"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`).","cause":"Attempting to `require()` `socks-proxy-agent` in a CommonJS context when the library is ESM-only since v7.0.0.","error":"Error [ERR_REQUIRE_ESM]: require() of ES Module .../node_modules/socks-proxy-agent/dist/index.js from ... not supported."},{"fix":"Ensure you are instantiating the class correctly: `const agent = new SocksProxyAgent(proxyUri);`","cause":"Instantiating `SocksProxyAgent` without the `new` keyword, or passing an incorrectly configured object as an agent.","error":"TypeError: The agent option must be an Agent object, got [object Object]"},{"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`).","cause":"The SOCKS proxy server rejected the provided username/password credentials, or they were not properly URL-encoded.","error":"Error: SOCKS proxy connection failed: Authentication failed"},{"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.","cause":"The hostname of the SOCKS proxy server could not be resolved by DNS.","error":"Error: getaddrinfo ENOTFOUND proxy.example.com"}],"ecosystem":"npm"}