nodejs/node · error · InvalidArgumentError

Proxy URL is mandatory

Error message

Proxy URL is mandatory

What it means

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.

Source

Thrown at deps/undici/src/lib/dispatcher/socks5-proxy-agent.js:44

/**
 * SOCKS5 proxy agent for dispatching requests through a SOCKS5 proxy
 */
class Socks5ProxyAgent extends DispatcherBase {
  constructor (proxyUrl, options = {}) {
    super()

    // Emit experimental warning only once
    if (!experimentalWarningEmitted) {
      process.emitWarning(
        'SOCKS5 proxy support is experimental and subject to change',
        'ExperimentalWarning'
      )
      experimentalWarningEmitted = true
    }

    if (!proxyUrl) {
      throw new InvalidArgumentError('Proxy URL is mandatory')
    }

    // Parse proxy URL
    const url = typeof proxyUrl === 'string' ? new URL(proxyUrl) : proxyUrl

    if (url.protocol !== 'socks5:' && url.protocol !== 'socks:') {
      throw new InvalidArgumentError('Proxy URL must use socks5:// or socks:// protocol')
    }

    this[kProxyUrl] = url
    this[kProxyHeaders] = options.headers || {}
    this[kProxyProtocol] = options.proxyTls ? 'https:' : 'http:'
    this[kRequestTls] = options.requestTls

    // Extract auth from URL or options
    this[kProxyAuth] = {
      username: options.username || (url.username ? decodeURIComponent(url.username) : null),
      password: options.password || (url.password ? decodeURIComponent(url.password) : null)

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Pass a non-empty socks5:// or socks:// URL as the first argument.
2. Gate construction on the presence of the SOCKS proxy URL.
3. Read the URL from a normalized config helper that errors clearly when absent.
4. Note SOCKS5 support is experimental; confirm the option name in your undici version.

Example fix

// before
new SOCKS5ProxyAgent(process.env.SOCKS_PROXY) // undefined when unset
// after
const p = process.env.SOCKS_PROXY
if (p) new SOCKS5ProxyAgent(p)

if (!proxyUrl) {
  throw new Error('A SOCKS5 proxy URL is required')
}
new SOCKS5ProxyAgent(proxyUrl, opts)

function isNonEmptyUrl(u) { return u != null && u !== '' }

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Proxy URL must use socks5:// or socks:// protocol
• UND_ERR_INVALID_ARG
• Proxy opts.clientFactory must be a function.
• opts.auth cannot be used in combination with opts.token
• Proxy-Authorization should be sent in ProxyAgent constructor

AI-assisted analysis of nodejs/node@1b2de5e052 (2026-08-13). Data as JSON: /api/errors/8a6a79c1c2aa08cf. Report an issue: GitHub.