websockets/ws · error · RangeError

Unsupported protocol version: ${opts.protocolVersion} (suppo

Error message

Unsupported protocol version: ${opts.protocolVersion} (supported versions: ${protocolVersions.join(', ')})

What it means

Thrown by initAsClient() (lib/websocket.js:694-699) when the protocolVersion option is not one of the supported values defined in the protocolVersions array ([8, 13]). The default is 13 (the current RFC 6455 version); version 8 is a legacy HyBi working-draft version still accepted. Any other value is rejected with RangeError before any network activity.

Source

Thrown at lib/websocket.js:695

    perMessageDeflate: true,
    followRedirects: false,
    maxRedirects: 10,
    ...options,
    socketPath: undefined,
    hostname: undefined,
    protocol: undefined,
    timeout: undefined,
    method: 'GET',
    host: undefined,
    path: undefined,
    port: undefined
  };

  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:') {

View on GitHub (pinned to ae1de54330)

Solutions

1. Use the default (omit protocolVersion) which is 13, the current standard.
2. If you genuinely need legacy HyBi-08, set protocolVersion: 8 explicitly as a number.
3. Validate the option type and value before constructing the client.

Example fix

// before
new WebSocket(url, [], { protocolVersion: 12 });

// after
new WebSocket(url, [], { protocolVersion: 13 }); // or simply omit it

const SUPPORTED = new Set([8, 13]);
function resolveProtocolVersion(opts) {
  const v = (opts && opts.protocolVersion) || 13;
  if (!SUPPORTED.has(v)) {
    throw new RangeError(`Unsupported protocolVersion ${v}; use 8 or 13`);
  }
  return v;
}

function isSupportedProtocolVersion(v) {
  return v === 8 || v === 13;
}

try {
  new WebSocket(url, protocols, opts);
} catch (err) {
  if (/Unsupported protocol version/.test(err.message)) {
    new WebSocket(url, protocols, { ...opts, protocolVersion: 13 });
  } else {
    throw err;
  }
}

When it happens

Trigger: Constructing a client with new WebSocket(url, protocols, { protocolVersion: X }) where X is not 8 or 13, e.g. 12, 7, '13' (string), or undefined coalescing to a bad value.

Common situations: Typing protocolVersion: 12 thinking it is a minor version; passing a string '13' instead of number 13; copy-pasting options across libraries with a different version scheme; bugs where a config value defaults to a non-version sentinel.

Related errors

• WebSocket is not open: readyState 0 (CONNECTING)
• Invalid URL: ${address}
• An invalid or duplicated subprotocol was specified
• ws does not work in the browser. Browser clients must use th
• Unexpected character at index ${i}

AI-assisted analysis of websockets/ws@ae1de54330 (2026-08-03). Data as JSON: /data/errors/9f50abe17f43cfa1.json. Report an issue: GitHub.