websockets/ws · error · RangeError

Unsupported protocol version

Error message

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

What it means

Thrown by initAsClient() at websocket.js:694-698 when the protocolVersion option is not in the supported set [8, 13] (defined at websocket.js:37). The default is 13 (the current RFC 6455 version); version 8 is retained for legacy compatibility. Any other value — including typos, strings, or stale numbers — is rejected before any network activity.

Solutions

1. Omit protocolVersion entirely — the default is 13, the current standard.
2. If you must set it, use the number 13: new WebSocket(url, [], { protocolVersion: 13 }).
3. Ensure the value is a number, not a string: Number(opts.protocolVersion), and that it equals 8 or 13.

Example fix

// before
const ws = new WebSocket(url, [], { protocolVersion: '13' });

// after
const ws = new WebSocket(url); // defaults to protocolVersion 13

const SUPPORTED = [8, 13];
function normalizeProtocolVersion(opts) {
  const v = Number(opts && opts.protocolVersion);
  return SUPPORTED.includes(v) ? v : 13; // default to standard
}
// usage: new WebSocket(url, [], { protocolVersion: normalizeProtocolVersion(options) });

function isSupportedProtocolVersion(v) {
  return typeof v === 'number' && (v === 8 || v === 13);
}

When it happens

Trigger: Passing { protocolVersion: 12 } or { protocolVersion: '13' } (string) or any non-8/13 number to the WebSocket constructor's options. The includes() check at line 694 fails and the RangeError is thrown synchronously during construction (because initAsClient runs in the constructor).

Common situations: Mistyping the version (e.g. 12, 14); passing a string '13' instead of the number 13; copying an outdated tutorial that referenced an old draft version (e.g. HyBi-07/10); a config loader coercing the value to a string.

Related errors

• Invalid URL
• An invalid or duplicated subprotocol was specified
• First argument must be a valid error code number
• The data size must not be greater than 125 bytes
• The message must not be greater than 123 bytes

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

Appendix: 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 c791e707ea)