nodejs/node · error · InvalidArgumentError

opts.auth cannot be used in combination with opts.token

Error message

opts.auth cannot be used in combination with opts.token

What it means

Thrown by the ProxyAgent constructor when both opts.auth and opts.token are supplied. Both encode Proxy-Authorization credentials (auth as a pre-base64 Basic value, token as a raw header value), so providing both is ambiguous and rejected. The library wants exactly one credential source to avoid silently preferring one over the other.

Source

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

    if (typeof clientFactory !== 'function') {
      throw new InvalidArgumentError('Proxy opts.clientFactory must be a function.')
    }

    const { proxyTunnel, connectTimeout } = opts

    super()

    const url = this.#getUrl(opts)
    const { href, origin, port, protocol, username, password, hostname: proxyHostname } = url

    this[kProxy] = { uri: href, protocol }
    this[kRequestTls] = opts.requestTls
    this[kProxyTls] = opts.proxyTls
    this[kProxyHeaders] = opts.headers || {}
    this[kTunnelProxy] = proxyTunnel

    if (opts.auth && opts.token) {
      throw new InvalidArgumentError('opts.auth cannot be used in combination with opts.token')
    } else if (opts.auth) {
      /* @deprecated in favour of opts.token */
      this[kProxyHeaders]['proxy-authorization'] = `Basic ${opts.auth}`
    } else if (opts.token) {
      this[kProxyHeaders]['proxy-authorization'] = opts.token
    } else if (username && password) {
      this[kProxyHeaders]['proxy-authorization'] = `Basic ${Buffer.from(`${decodeURIComponent(username)}:${decodeURIComponent(password)}`).toString('base64')}`
    } else if (username) {
      this[kProxyHeaders]['proxy-authorization'] = `Basic ${Buffer.from(`${decodeURIComponent(username)}:`).toString('base64')}`
    }

    const connect = buildConnector({ timeout: connectTimeout, ...opts.proxyTls })
    const connectHTTP1 = buildConnector({ timeout: connectTimeout, ...opts.proxyTls, allowH2: false })
    this[kConnectEndpoint] = buildConnector({ timeout: connectTimeout, ...opts.requestTls })
    this[kConnectEndpointHTTP1] = buildConnector({ timeout: connectTimeout, ...opts.requestTls, allowH2: false })

    const agentFactory = opts.factory || defaultAgentFactory
    const factory = (origin, options) => {

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Use exactly one of opts.auth (deprecated, Basic) or opts.token (raw header value).
2. Prefer opts.token going forward since auth is deprecated.
3. Strip auth from shared/default config before adding token.
4. Validate that not both keys are set in your config loader.

Example fix

// before
new ProxyAgent({ uri, auth: creds, token: tok })
// after
new ProxyAgent({ uri, token: tok })

if (cfg.auth && cfg.token) {
  throw new Error('Provide either auth or token, not both')
}
new ProxyAgent({ uri, auth: cfg.auth, token: cfg.token })

When it happens

Trigger: Passing { uri, auth: 'dXNlcjpwYXNz', token: 'Bearer xyz' } together; merging two config sources where one set auth and another set token; migrating from the deprecated auth to token without removing the old field.

Common situations: Layered config (defaults + overrides) that accidentally sets both; copy-paste between examples using different credential options; deprecated auth left in place after adding token.

Related errors

• Proxy opts.clientFactory must be a function.
• Proxy-Authorization should be sent in ProxyAgent constructor
• UND_ERR_INVALID_ARG
• 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/c64a846a5a206c2a. Report an issue: GitHub.