{"record":{"id":"8a6a79c1c2aa08cf","repo":"nodejs/node","slug":"proxy-url-is-mandatory","errorCode":null,"errorMessage":"Proxy URL is mandatory","messagePattern":"Proxy URL is mandatory","errorType":"exception","errorClass":"InvalidArgumentError","httpStatus":null,"severity":"error","filePath":"deps/undici/src/lib/dispatcher/socks5-proxy-agent.js","lineNumber":44,"sourceCode":"\n/**\n * SOCKS5 proxy agent for dispatching requests through a SOCKS5 proxy\n */\nclass Socks5ProxyAgent extends DispatcherBase {\n  constructor (proxyUrl, options = {}) {\n    super()\n\n    // Emit experimental warning only once\n    if (!experimentalWarningEmitted) {\n      process.emitWarning(\n        'SOCKS5 proxy support is experimental and subject to change',\n        'ExperimentalWarning'\n      )\n      experimentalWarningEmitted = true\n    }\n\n    if (!proxyUrl) {\n      throw new InvalidArgumentError('Proxy URL is mandatory')\n    }\n\n    // Parse proxy URL\n    const url = typeof proxyUrl === 'string' ? new URL(proxyUrl) : proxyUrl\n\n    if (url.protocol !== 'socks5:' && url.protocol !== 'socks:') {\n      throw new InvalidArgumentError('Proxy URL must use socks5:// or socks:// protocol')\n    }\n\n    this[kProxyUrl] = url\n    this[kProxyHeaders] = options.headers || {}\n    this[kProxyProtocol] = options.proxyTls ? 'https:' : 'http:'\n    this[kRequestTls] = options.requestTls\n\n    // Extract auth from URL or options\n    this[kProxyAuth] = {\n      username: options.username || (url.username ? decodeURIComponent(url.username) : null),\n      password: options.password || (url.password ? decodeURIComponent(url.password) : null)","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/nodejs/node/blob/1b2de5e052fc0fb95fd7fb6846dcec4ade598e9e/deps/undici/src/lib/dispatcher/socks5-proxy-agent.js#L26-L62","documentation":"Thrown by the SOCKS5ProxyAgent constructor when proxyUrl is falsy. The agent needs a SOCKS proxy endpoint to tunnel through; without one it cannot establish the relay, so it rejects before parsing. This fires after the one-time experimental warning is emitted.","triggerScenarios":"Constructing SOCKS5ProxyAgent(undefined) or SOCKS5ProxyAgent(''); passing an opts object whose proxy URL field is missing. The constructor expects proxyUrl as the first positional argument, not inside an options bag.","commonSituations":"Env var ALL_PROXY/SOCKS_PROXY unset but the agent is always constructed; config read from the wrong key; conditional SOCKS usage that builds the agent in the no-proxy branch.","solutions":["Pass a non-empty socks5:// or socks:// URL as the first argument.","Gate construction on the presence of the SOCKS proxy URL.","Read the URL from a normalized config helper that errors clearly when absent.","Note SOCKS5 support is experimental; confirm the option name in your undici version."],"exampleFix":"// before\nnew SOCKS5ProxyAgent(process.env.SOCKS_PROXY) // undefined when unset\n// after\nconst p = process.env.SOCKS_PROXY\nif (p) new SOCKS5ProxyAgent(p)","handlingStrategy":"validation","validationCode":"if (!proxyUrl) {\n  throw new Error('A SOCKS5 proxy URL is required')\n}\nnew SOCKS5ProxyAgent(proxyUrl, opts)","typeGuard":"function isNonEmptyUrl(u) { return u != null && u !== '' }","tryCatchPattern":null,"preventionTips":["Gate SOCKS5ProxyAgent construction on a present proxy URL.","Note SOCKS5 support is experimental; verify the API for your version.","Centralize proxy-URL resolution in one config helper."],"tags":["undici","proxy","socks5","invalid-arg"],"backgroundTag":null,"analyzedSha":"1b2de5e052fc0fb95fd7fb6846dcec4ade598e9e","analyzedAt":"2026-08-13T00:53:24.642Z","schemaVersion":2},"datasetVersion":"2026-08-13T04:17:16.726Z"}