EC
ERR_HTTP2_STATUS_101
Node.jsERRORNotableHTTP/2HIGH confidence

HTTP/2 does not support status 101 (Switching Protocols)

Production Risk

Causes stream failure; HTTP/2 servers must use a different mechanism for WebSocket.

What this means

Thrown when an HTTP/2 stream attempts to respond with status code 101. HTTP/2 does not support the upgrade mechanism that status 101 represents. WebSocket over HTTP/2 requires the extended CONNECT mechanism defined in RFC 8441.

Why it happens
  1. 1Attempting to upgrade to WebSocket using the HTTP/1.1 upgrade mechanism over HTTP/2
  2. 2HTTP/1.1 middleware sending 101 without checking the underlying protocol
How to reproduce

Triggered when stream.respond() is called with :status 101 on an HTTP/2 stream.

trigger — this will error
trigger — this will error
server.on('stream', (stream) => {
  stream.respond({ ':status': 101 }); // throws
});

expected output

Error [ERR_HTTP2_STATUS_101]: HTTP status code 101 (Switching Protocols) is forbidden in HTTP/2

Fix

Use an HTTP/1.1 server for WebSocket upgrades

WHEN When you need WebSocket support

Use an HTTP/1.1 server for WebSocket upgrades
const http = require('http');
const { WebSocketServer } = require('ws');
const server = http.createServer();
const wss = new WebSocketServer({ server });
server.listen(3000);

Why this works

WebSocket upgrade (101) is an HTTP/1.1 feature; using HTTP/1.1 avoids the HTTP/2 restriction.

Code examples
Triggerjs
server.on('stream', (stream) => {
  stream.respond({ ':status': 101 }); // throws
});  // this triggers ERR_HTTP2_STATUS_101
Handle in try/catchjs
try {
  // operation that may throw ERR_HTTP2_STATUS_101
  riskyOperation()
} catch (err) {
  if (err.code === 'ERR_HTTP2_STATUS_101') {
    console.error('ERR_HTTP2_STATUS_101:', err.message)
  } else {
    throw err
  }
}
Defensive pattern to avoid itjs
// Validate inputs before calling the operation
function safe_err_http2_status_101(...args) {
  // validate args here
  return performOperation(...args)
}
What not to do

✕ Send status 101 over HTTP/2

The HTTP/2 spec explicitly forbids it; use extended CONNECT (RFC 8441) or HTTP/1.1.

Sources
Official documentation ↗

Node.js Error Codes Documentation

Content generated with AI assistance and reviewed for accuracy. Found an error? hello@errcodes.dev

← All Node.js errors