426 Upgrade Required

Meaning & Description

Common Causes

• Client failed to include the `Connection: Upgrade` and `Upgrade: websocket` headers when accessing a WebSocket route.
• The server configuration enforces a minimum protocol version that the client does not support.
• Reverse proxy misconfiguration stripping out protocol upgrade headers before reaching the backend.

How to fix a 426 error

1. Check the `Upgrade` header in the 426 response to identify which protocol the server demands.
2. If connecting to a WebSocket, ensure your client library sends `Upgrade: websocket` and `Connection: Upgrade`.
3. Verify that your proxy or load balancer (e.g., Nginx, HAProxy) is configured to proxy WebSocket upgrade headers.
4. Upgrade your client tool (e.g., curl, browser, HTTP library) to support the requested protocol (like HTTP/2).

Browser & SEO Behaviour

Code Examples

GET /chat HTTP/1.1
Host: api.example.com

# Missing Upgrade headers

app.get('/chat', (req, res) => {
  if (req.headers['upgrade'] !== 'websocket') {
    res.set('Upgrade', 'websocket');
    res.set('Connection', 'Upgrade');
    return res.status(426).send("Upgrade Required: Please use WebSockets.");
  }
  // Handle WebSocket
});

@app.get("/ws-endpoint")
def enforce_websocket(request: Request):
    if request.headers.get("upgrade") != "websocket":
        headers = {"Upgrade": "websocket", "Connection": "Upgrade"}
        raise HTTPException(status_code=426, detail="Upgrade Required", headers=headers)
    return {"status": "ok"}

func wsHandler(w http.ResponseWriter, r *http.Request) {
    if r.Header.Get("Upgrade") != "websocket" {
        w.Header().Set("Upgrade", "websocket")
        w.Header().Set("Connection", "Upgrade")
        http.Error(w, "Upgrade Required", 426)
        return
    }
    // Upgrade connection...
}

[HttpGet("chat")]
public IActionResult ChatEndpoint() {
    if (!HttpContext.WebSockets.IsWebSocketRequest) {
        Response.Headers.Add("Upgrade", "websocket");
        Response.Headers.Add("Connection", "Upgrade");
        return StatusCode(426, "Please connect using WebSockets.");
    }
    return Ok();
}

curl -v http://api.example.com/chat \
  -H "Connection: Upgrade" \
  -H "Upgrade: websocket"

Raw HTTP Response Example

HTTP/1.1 426 Upgrade Required
Connection: Upgrade
Upgrade: websocket
Content-Type: text/plain
Content-Length: 43

This endpoint requires a WebSocket upgrade.

Real-world Examples

Frequently Asked Questions

Developer Tips

• When building a WebSocket endpoint, always gracefully handle standard HTTP requests by returning a 426 Upgrade Required with a clear text explanation, rather than just crashing or returning a 400 Bad Request.
• If using Nginx as a proxy for WebSockets, ensure you include `proxy_set_header Upgrade $http_upgrade;` and `proxy_set_header Connection 'upgrade';`.
• Never configure your main homepage or API root to require an upgrade, as this will completely break SEO crawlers and older clients.

Interview Questions

These are questions you might face in a backend or API design interview that touch on HTTP 426.