Spring rejects the WebSocket handshake: Upgrade header is null
Handshake failed due to invalid Upgrade header: nullShort answer
The message means the request reached Spring without an Upgrade: websocket header, so it was an ordinary HTTP request. Either something other than a WebSocket client called the URL, or a reverse proxy removed the header on the way. Test the endpoint directly with curl, then fix the proxy.
Fix it fast
1Find out which cause you have
Send a hand-made WebSocket handshake straight to the Spring port, with no proxy in between. A working endpoint answers 101.
curl -i -N \ -H "Connection: Upgrade" -H "Upgrade: websocket" \ -H "Sec-WebSocket-Version: 13" \ -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \ http://localhost:8080/myHandler2Match what you see, then jump to its fix
What does the error look like?
Handshake failed due to invalid Upgrade header: nullHTTP status 200 instead of 101 when opening the WebSocketWebSocket connection to 'ws://host/myHandler' failed
Cause 1 of 2
The caller sent a normal HTTP request
1Check
A valid handshake is a GET with Upgrade: websocket, Connection: Upgrade, a Sec-WebSocket-Key and version 13. A browser address bar or fetch call sends none of that. When the answer is not 101, a client treats it as ordinary HTTP, which is why a 200 can appear.
curl -i http://localhost:8080/myHandler2Fix
Connect with a WebSocket client and the ws:// or wss:// scheme, and use the exact path from addHandler.
// server
registry.addHandler(myHandler(), "/myHandler");
// browser
const ws = new WebSocket("ws://localhost:8080/myHandler");3Verify
The handshake curl from the first step returns HTTP/1.1 101.
curl -i -N -H "Connection: Upgrade" -H "Upgrade: websocket" -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" http://localhost:8080/myHandlerConfirmed by datatracker.ietf.org
Cause 2 of 2
A reverse proxy does not pass the Upgrade header
1Check
Upgrade and Connection are hop-by-hop headers, so nginx does not forward them to the backend unless told to.
grep -rn "proxy_set_header Upgrade" /etc/nginx/2Fix
Pass both headers explicitly in the location that fronts Spring. On nginx older than 1.29.7 also keep proxy_http_version 1.1.
location /myHandler {
proxy_pass http://127.0.0.1:8080;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
}3Verify
Reload nginx and repeat the handshake against the public host name.
sudo nginx -t && sudo systemctl reload nginxConfirmed by nginx.org
How do I stop it coming back?
- Keep the WebSocket path in one place and share it between the Spring config and the frontend.
- Add the Upgrade headers to the proxy config at the same time you add the endpoint.
- Keep the curl handshake in your deploy notes as a smoke test.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Back end
Chrome shows net::ERR_INCOMPLETE_CHUNKED_ENCODING on a PHP page
The page loads partly, then the response stops
The browser got a chunked response that ended before its final zero-length chunk, so the connection closed mid-page.
2 causes, each with a fixBack end
CodeIgniter works locally but every page is 404 on the live server
The requested URL was not found on this server.
A 404 on the live server comes from one of four places: the document root is not the public folder, Apache ignores .htaccess or nginx has no try_files rule, the route is not defined because auto routing is off, or the controller file name differs from its class in case.
5 causes, each with a fixBack end
Django form POST returns 403 Forbidden: CSRF verification failed
CSRF verification failed. Request aborted.
Django rejects an unsafe request when the CSRF cookie or the form token is missing or wrong, or when the Origin or Referer check fails.
5 causes, each with a fixBack end
Express rejects a request body as too large
413 (Request Entity Too Large) returned by nginx in front of the app
A 413 means a body was bigger than a size limit.
3 causes, each with a fixBack end
Laravel file upload returns 413 behind nginx
413 Content Too Large
A 413 means a limit refused the request body before Laravel could use it.
3 causes, each with a fixBack end
Laravel Echo connects to Reverb but no events arrive
WebSocket connection to 'ws://localhost:80/app/...' failed
Reverb events fail to arrive for four common reasons: no queue worker is running, BROADCAST_CONNECTION is not reverb, the Echo client points at the wrong host or port, or a custom broadcastAs name is listened for without a leading dot.
4 causes, each with a fix