nats-io/nats-server · error

%s - websocket handshake error: %s

Error message

%s - websocket handshake error: %s

What it means

Created by wsReturnHTTPError() when a websocket upgrade request fails validation. It combines the client's RemoteAddr with a specific rejection reason (bad method, missing/invalid Sec-WebSocket headers, bad version, etc.), sends the corresponding HTTP error response, and is returned to the caller to log. It denotes a malformed or unauthorized handshake, not a server fault.

Source

Thrown at server/websocket.go:1023

						} else if strings.EqualFold(p, wsPMCCliNoCtx) {
							cnc = true
						}
						if snc && cnc {
							return true, true
						}
					}
					return true, false
				}
			}
		}
	}
	return false, false
}

// Send an HTTP error with the given `status` to the given http response writer `w`.
// Return an error created based on the `reason` string.
func wsReturnHTTPError(w http.ResponseWriter, r *http.Request, status int, reason string) error {
	err := fmt.Errorf("%s - websocket handshake error: %s", r.RemoteAddr, reason)
	w.Header().Set("Sec-Websocket-Version", "13")
	http.Error(w, http.StatusText(status), status)
	return err
}

// If the server is configured to accept any origin, then this function returns
// `nil` without checking if the Origin is present and valid. This is also
// the case if the request does not have the Origin header.
// Otherwise, this will check that the Origin matches the same origin or
// any origin in the allowed list.
func (w *srvWebsocket) checkOrigin(r *http.Request) error {
	w.mu.RLock()
	checkSame := w.sameOrigin
	listEmpty := len(w.allowedOrigins) == 0
	w.mu.RUnlock()
	if !checkSame && listEmpty {
		return nil
	}

View on GitHub (pinned to 3a66a489d2)

Solutions

1. Read the reason portion to identify which handshake requirement the client failed
2. Ensure the client sends a proper GET upgrade request with Sec-WebSocket-Key, Version: 13, and correct headers
3. If the client is trusted but blocked by auth/origin checks, adjust server websocket options (allowed origins, users, TLS)

When it happens

Trigger: Thrown at server/websocket.go:1023 when the library encounters an invalid state.

Common situations: See trigger scenarios.

Understand the failure class

• SSL/TLS and certificate errors — how TLS handshakes and certificate validation fail.

AI-assisted analysis of nats-io/nats-server@3a66a489d2 (2026-09-02). Data as JSON: /api/errors/f44c11ebb3428a7d. Report an issue: GitHub.