nodejs/node · error · InvalidArgumentError

Proxy URL must use socks5:// or socks:// protocol

Error message

Proxy URL must use socks5:// or socks:// protocol

What it means

Thrown by the SOCKS5ProxyAgent constructor when the parsed proxy URL's protocol is neither 'socks5:' nor 'socks:'. The agent only speaks SOCKS5, so http://, https://, socks4:, or any other scheme is rejected after the URL is parsed. The string-or-URL input is normalized to a URL before the check.

Source

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

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

    // Create connector for proxy connection
    this[kConnector] = options.connect || buildConnector({
      ...options.proxyTls,
      servername: options.proxyTls?.servername || url.hostname
    })

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Use a socks5:// or socks:// URL for SOCKS5ProxyAgent.
2. If the endpoint is an HTTP proxy, use ProxyAgent instead.
3. Validate the URL protocol in your config loader before constructing the agent.
4. Normalize env-provided URLs to the expected scheme.

Example fix

// before
new SOCKS5ProxyAgent(process.env.HTTP_PROXY) // 'http://...'
// after
new SOCKS5ProxyAgent('socks5://proxy.internal:1080')

const u = typeof proxyUrl === 'string' ? new URL(proxyUrl) : proxyUrl
if (u.protocol !== 'socks5:' && u.protocol !== 'socks:') {
  throw new Error(`SOCKS5ProxyAgent requires socks5:// or socks://, got ${u.protocol}`)
}
new SOCKS5ProxyAgent(u)

function isSocksUrl(origin) {
  const u = typeof origin === 'string' ? new URL(origin) : origin
  return u instanceof URL && (u.protocol === 'socks5:' || u.protocol === 'socks:')
}

When it happens

Trigger: Passing 'http://proxy:1080' or 'socks4://proxy' to SOCKS5ProxyAgent; passing a URL instance with the wrong protocol; a typo'd scheme like 'socks5://' vs 'sock5://'.

Common situations: Reusing an HTTP_PROXY value for SOCKS config; copy-paste between ProxyAgent and SOCKS5ProxyAgent; env var pointing at a non-SOCKS endpoint; confusion between socks4 and socks5.

Related errors

• Proxy URL is mandatory
• UND_ERR_INVALID_ARG
• UND_ERR_INVALID_ARG
• Proxy opts.clientFactory must be a function.
• opts.auth cannot be used in combination with opts.token

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