nodejs/node · error · InvalidArgumentError

UND_ERR_INVALID_ARG

UND_ERR_INVALID_ARG

Error message

Invalid URL protocol: the URL must start with `http:` or `https:`.

What it means

parseURL throws this when the URL was supplied as a string and, after construction via new URL(), the origin (or protocol fallback) is not prefixed with http: or https:. Undici only speaks HTTP/1.1 over http/https, so any other scheme (ftp:, file:, data:, ws:) is rejected.

Source

Thrown at deps/undici/src/lib/core/util.js:169

        value[5] === ':'
      )
    )
  )
}

/**
 * @param {string|URL|Record<string,string>} url
 * @returns {URL}
 */
function parseURL (url) {
  if (typeof url === 'string') {
    /**
     * @type {URL}
     */
    url = new URL(url)

    if (!isHttpOrHttpsPrefixed(url.origin || url.protocol)) {
      throw new InvalidArgumentError('Invalid URL protocol: the URL must start with `http:` or `https:`.')
    }

    return url
  }

  if (!url || typeof url !== 'object') {
    throw new InvalidArgumentError('Invalid URL: The URL argument must be a non-null object.')
  }

  if (!(url instanceof URL)) {
    if (url.port != null && url.port !== '' && isValidPort(url.port) === false) {
      throw new InvalidArgumentError('Invalid URL: port must be a valid integer or a string representation of an integer.')
    }

    if (url.path != null && typeof url.path !== 'string') {
      throw new InvalidArgumentError('Invalid URL path: the path must be a string or null/undefined.')
    }

View on GitHub (pinned to 1b2de5e052)

Solutions

1. Ensure the URL string begins with 'http://' or 'https://'.
2. If the scheme is variable, normalize it before passing: prepend 'https://' when missing.
3. For WebSocket traffic use a ws client, not undici fetch/request.
4. Validate URLs at the config boundary with new URL() and check .protocol.

Example fix

// before
await request('example.com/path')
// after
await request('https://example.com/path')

function assertHttpUrl(url) {
  const u = new URL(url)
  if (u.protocol !== 'http:' && u.protocol !== 'https:') {
    throw new TypeError(`Expected http(s) URL, got ${u.protocol}`)
  }
  return u
}

function isHttpUrlString(s) {
  return typeof s === 'string' && /^https?:\/\//i.test(s)
}

When it happens

Trigger: Calling any undici entry point (request, fetch, Pool, Client, Agent) with a string URL whose scheme is not http/https, e.g. 'ftp://...', 'file:///...', 'ws://...', or a URL missing its scheme entirely.

Common situations: Passing a bare hostname ('example.com') without a scheme; feeding a WebSocket ws:// URL to fetch; reading URLs from config that omitted the protocol; mixing URL types across libraries.

Related errors

• UND_ERR_INVALID_ARG
• Query params cannot be passed when url already contains "?"
• Invalid URL: ${url}
• UND_ERR_INVALID_ARG
• UND_ERR_INVALID_ARG

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