nodejs/node · error · InvalidArgumentError

UND_ERR_INVALID_ARG

UND_ERR_INVALID_ARG

Error message

invalid url

What it means

Thrown by undici's makeDispatcher (the wrapper behind request/stream/fetch/pipeline/upgrade/connect/quickLoad) when the url argument is missing or not a string, plain object, or URL instance. Code is UND_ERR_INVALID_ARG. It is a synchronous argument-type guard before any networking occurs.

Source

Thrown at deps/undici/src/index.js:82

const SqliteCacheStore = require('./lib/cache/sqlite-cache-store')
module.exports.cacheStores.SqliteCacheStore = SqliteCacheStore

module.exports.buildConnector = buildConnector
module.exports.errors = errors
module.exports.util = {
  parseHeaders: util.parseHeaders,
  headerNameToString: util.headerNameToString
}

function makeDispatcher (fn) {
  return (url, opts, handler) => {
    if (typeof opts === 'function') {
      handler = opts
      opts = null
    }

    if (!url || (typeof url !== 'string' && typeof url !== 'object' && !(url instanceof URL))) {
      throw new InvalidArgumentError('invalid url')
    }

    if (opts != null && typeof opts !== 'object') {
      throw new InvalidArgumentError('invalid opts')
    }

    if (opts && opts.path != null) {
      if (typeof opts.path !== 'string') {
        throw new InvalidArgumentError('invalid opts.path')
      }

      let path = opts.path
      if (!opts.path.startsWith('/')) {
        path = `/${path}`
      }

      url = new URL(util.parseOrigin(url).origin + path)
    } else {

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Ensure the url argument is a non-empty string or a URL/URL-like object before the call.
2. Default/validate the value at the call site: const url = process.env.API_URL; if (!url) throw ...
3. Construct the URL explicitly with new URL(...) upstream so it is always a URL instance.
4. Check for undefined return from the upstream source of the URL.

Example fix

// before
await dispatcher.request(endpoint)        // endpoint is undefined
// after
if (!endpoint) throw new Error('endpoint missing')
await dispatcher.request(new URL(endpoint))

function resolveUrl(u) {
  if (!u) throw new Error('url required')
  return typeof u === 'string' || u instanceof URL ? u : new URL(u)
}

function isValidUndiciUrl(u: unknown): u is string | URL | Record<string, unknown> {
  return typeof u === 'string' || u instanceof URL || (typeof u === 'object' && u !== null)
}

try {
  await dispatcher.request(url, opts)
} catch (err) {
  if (err.code === 'UND_ERR_INVALID_ARG' && /invalid url/.test(err.message)) {
    throw new Error(`Invalid request: url argument missing or wrong type (${url})`)
  }
  throw err
}

When it happens

Trigger: Calling any undici dispatcher method (request, stream, pipeline, fetch, upgrade, connect) with url = undefined, null, a number, boolean, or any non-string/non-object value.

Common situations: Reading URL from an env var or config that is undefined; passing a parsed object that is not a URL; template-literal producing empty string; variable renamed/typo; async source resolved to undefined.

Related errors

• UND_ERR_INVALID_ARG
• UND_ERR_INVALID_ARG
• UND_ERR_INVALID_ARG
• UND_ERR_INVALID_ARG
• UND_ERR_INVALID_ARG

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