nodejs/node · error · InvalidArgumentError

UND_ERR_INVALID_ARG

UND_ERR_INVALID_ARG

Error message

Proxy URL is mandatory

What it means

Thrown by Http1ProxyWrapper's constructor (inside proxy-agent.js) when proxyUrl is falsy. Http1ProxyWrapper wraps a single upstream Client pointed at a proxy; without a proxy URL it has nothing to connect to, so it rejects before building the underlying Client.

Source

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

function defaultAgentFactory (origin, opts) {
  if (opts.connections === 1) {
    return new Client(origin, opts)
  }
  return new Pool(origin, opts)
}

function shouldProxyTunnel (requestProtocol, proxyTunnel) {
  return proxyTunnel === true || requestProtocol !== 'http:'
}

class Http1ProxyWrapper extends DispatcherBase {
  #client
  #proxyServername

  constructor (proxyUrl, { headers = {}, connect, factory, proxyServername }) {
    if (!proxyUrl) {
      throw new InvalidArgumentError('Proxy URL is mandatory')
    }

    super()

    this[kProxyHeaders] = headers
    this.#proxyServername = proxyServername
    if (factory) {
      this.#client = factory(proxyUrl, { connect })
    } else {
      this.#client = new Client(proxyUrl, { connect })
    }
  }

  [kDispatch] (opts, handler) {
    const onResponseStart = handler.onResponseStart
    handler.onResponseStart = function (controller, statusCode, data, statusMessage) {
      if (statusCode === 407) {
        if (typeof handler.onResponseError === 'function') {

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Provide a non-empty proxy URL string or URL object to Http1ProxyWrapper.
2. Gate wrapper construction on the presence of a proxy URL so the no-proxy path skips it.
3. Read the proxy URL from a normalized config helper that errors clearly when it is missing.
4. Prefer the higher-level ProxyAgent API, which gives a clearer 'Proxy uri is mandatory' message.

Example fix

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

if (!proxyUrl) {
  throw new Error('A proxy URL is required to build Http1ProxyWrapper')
}
new Http1ProxyWrapper(proxyUrl, opts)

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

When it happens

Trigger: Constructing Http1ProxyWrapper(undefined) or Http1ProxyWrapper(''), or passing an opts object whose proxy URL field resolved to undefined. Http1ProxyWrapper is typically created internally by ProxyAgent when proxyTunnel is false, fed by ProxyAgent.#getUrl(opts).

Common situations: Env var HTTP_PROXY/HTTPS_PROXY unset but the code always constructs the wrapper; misrouted config where opts.uri is read under a different key; conditional proxy logic that builds the wrapper even in the no-proxy branch.

Related errors

• 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
• Proxy URL is mandatory
• Proxy URL must use socks5:// or socks:// protocol

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