What causes "Invalid URL: ${address}" in websockets/ws?

Always include the scheme: new WebSocket('ws://localhost:8080') or 'wss://host/path'.

websockets/ws · error · SyntaxError

Invalid URL

Error message

Invalid URL: ${address}

What it means

Thrown by initAsClient() at websocket.js:706-710 when the address argument cannot be parsed by `new URL(address)`. The constructor accepts a string or a URL object; if it is a string, the WHATWG URL parser runs and any failure (catch block at line 708) is converted into a SyntaxError with the original address in the message. This happens synchronously, during WebSocket construction.

Solutions

Always include the scheme: new WebSocket('ws://localhost:8080') or 'wss://host/path'.
Validate/normalize the address before constructing: new URL(address) in your own try/catch, or build it from components.
If the address may be incomplete, prefix a default scheme and host before passing it in.

Example fix

// before
const ws = new WebSocket('localhost:8080/ws'); // no scheme -> throws

// after
const ws = new WebSocket('ws://localhost:8080/ws');

Defensive patterns

Strategy: validation

Validate before calling

function toWebSocketUrl(address) {
  if (address instanceof URL) return address;
  // ensure a scheme is present
  if (!/^[a-z][a-z0-9+.-]*:///i.test(address)) {
    address = 'ws://' + address;
  }
  return new URL(address); // throws if still invalid
}

Type guard

function isParseableWsUrl(address) {
  try { new URL(address); return true; } catch { return false; }
}

Prevention

Always include the scheme (ws:// or wss://) in address strings.
Validate addresses with new URL() in a try/catch before constructing the WebSocket.
Normalize config/env-sourced URLs (add default scheme/host) before passing them in.

When it happens

Trigger: Passing a malformed string to new WebSocket(address), e.g. 'localhost:8080' (no scheme), 'ws://[broken', '' (empty), or a value with embedded spaces/control characters. If address is already a URL instance it is used directly (line 703-704) and never hits this branch; only strings go through the try/catch.

Common situations: Forgetting the ws:// or wss:// scheme (a bare host:port is not a valid URL); constructing the URL from env vars that are empty or missing; a config typo; user input that wasn't validated; relative paths passed as the address.

Related errors

AI-assisted analysis of websockets/ws@c791e707ea (2026-08-06). Data as JSON: /api/errors/dc0091bb3984f289. Report an issue: GitHub.

Appendix: source

Thrown at lib/websocket.js:709

  websocket._autoPong = opts.autoPong;
  websocket._closeTimeout = opts.closeTimeout;

  if (!protocolVersions.includes(opts.protocolVersion)) {
    throw new RangeError(
      `Unsupported protocol version: ${opts.protocolVersion} ` +
        `(supported versions: ${protocolVersions.join(', ')})`
    );
  }

  let parsedUrl;

  if (address instanceof URL) {
    parsedUrl = address;
  } else {
    try {
      parsedUrl = new URL(address);
    } catch {
      throw new SyntaxError(`Invalid URL: ${address}`);
    }
  }

  if (parsedUrl.protocol === 'http:') {
    parsedUrl.protocol = 'ws:';
  } else if (parsedUrl.protocol === 'https:') {
    parsedUrl.protocol = 'wss:';
  }

  websocket._url = parsedUrl.href;

  const isSecure = parsedUrl.protocol === 'wss:';
  const isIpcUrl = parsedUrl.protocol === 'ws+unix:';
  let invalidUrlMessage;

  if (parsedUrl.protocol !== 'ws:' && !isSecure && !isIpcUrl) {
    invalidUrlMessage =
      'The URL\'s protocol must be one of "ws:", "wss:", ' +

View on GitHub (pinned to c791e707ea)