Why does Membrane API Gateway return 401 Protocol upgrade has been denied?

The client sent a request with an Upgrade header asking for a protocol that the API does not allow. Membrane refuses to forward the upgrade to the backend.

How do I allow WebSockets in Membrane?

Add the webSocket plugin to the flow of the API. Only this plugin marks WebSocket upgrades as allowed.

How do I hide the details in Membrane error responses?

Enable production mode by adding a configuration document with production: true to your apis.yaml. Membrane then leaves out detailed information from error responses.

401 Unauthorized: Protocol Upgrade Denied

Membrane API Gateway returns 401 Unauthorized with the title Protocol upgrade has been denied. when a client asks to switch to a protocol the API does not allow. The request carries an Upgrade header, and Membrane refuses to forward it to the backend.

The Error Response

The response contains the status 401 Unauthorized, the title Protocol upgrade has been denied., the problem type https://membrane-api.io/problems/gateway and a link to this page. In development mode, it also lists the name and URL of the API that received the request, so you can tell which API rejected the upgrade. The type gateway means that the problem lies between Membrane and an upstream system, not in the client's request.

How Membrane Handles Protocol Upgrades

A client asks for a protocol switch with the Upgrade header, for example Upgrade: websocket. Membrane forwards such a request only if the API allows the requested protocol. Membrane handles websocket, tcp and HTTP/2 (h2, h2c). Every other value is denied.

Common Causes

WebSocket Upgrade Without the webSocket Plugin

The client sends Upgrade: websocket, but the API has no webSocket plugin in its flow. Only this plugin allows WebSocket upgrades:

api:
  port: 2000
  flow:
    - webSocket: {}
  target:
    url: http://localhost:8080

api:
  port: 2000
  flow:
    - webSocket: {}
  target:
    url: http://localhost:8080

TCP Upgrade Without the tcp Element

The client sends Upgrade: tcp, but the tcp element is not enabled for the API. Add it where the configuration reference permits it for the API.

An Unsupported Upgrade Protocol

The client asks for a protocol other than websocket, tcp, h2 or h2c. Membrane denies these upgrades for every API.

How to Fix It

Check the Upgrade header of the failing request.
To allow WebSockets, add the webSocket plugin to the flow of the API. To allow TCP upgrades, enable the tcp element.
If the upgrade is not intended, send the request without the Upgrade header.

Hide Details in Production

By default, Membrane runs in development mode and adds details to error responses that help you find the problem, including the link to this page. These details may reveal information about your setup. In production, turn them off:

configuration:
  production: true

configuration:
  production: true

Add the configuration document to your apis.yaml and separate it from the APIs with ---.

In production mode, the response keeps the status, title and problem type, but leaves out the detail and the link to this page.