{"record":{"id":"ae42071de0ebba1c","repo":"hasura/graphql-engine","slug":"sec-websocket-protocol-header-0","errorCode":null,"errorMessage":"{SEC_WEBSOCKET_PROTOCOL} header: {0}","messagePattern":"(.+?) header: (.+?)","errorType":"http","errorClass":"WebSocketError","httpStatus":400,"severity":"error","filePath":"v3/crates/graphql/graphql-ws/src/websocket/mod.rs","lineNumber":118,"sourceCode":"                        .insert(SEC_WEBSOCKET_ID, websocket_id.to_string().parse()?);\n                    Ok(response)\n                })\n            },\n        );\n\n        result.unwrap_or_else(IntoResponse::into_response)\n    }\n}\n\n/// Error types for WebSocket connections.\n#[derive(Debug, thiserror::Error)]\npub enum WebSocketError {\n    /// Error when the Sec-WebSocket-Protocol header is missing\n    #[error(\"Missing {SEC_WEBSOCKET_PROTOCOL} header\")]\n    MissingProtocolHeader,\n\n    /// Error when the header value cannot be converted to a string\n    #[error(\"{SEC_WEBSOCKET_PROTOCOL} header: {0}\")]\n    InvalidHeaderValue(#[from] ToStrError),\n\n    /// Error when the GraphQL WebSocket protocol is not included\n    #[error(\"Expecting {} protocol\", protocol::GRAPHQL_WS_PROTOCOL)]\n    ExpectingGraphqlWsProtocol,\n\n    /// Error when setting the WebSocket ID header value fails in response\n    #[error(\"Unable to set {SEC_WEBSOCKET_ID} header value: {0}\")]\n    WebSocketIdInvalidHeaderValue(#[from] InvalidHeaderValue),\n}\n\nimpl tracing_util::TraceableError for WebSocketError {\n    fn visibility(&self) -> tracing_util::ErrorVisibility {\n        match self {\n            Self::MissingProtocolHeader\n            | Self::ExpectingGraphqlWsProtocol\n            | Self::InvalidHeaderValue(_) => tracing_util::ErrorVisibility::User,\n            Self::WebSocketIdInvalidHeaderValue(_) => tracing_util::ErrorVisibility::Internal,","sourceCodeStart":100,"sourceCodeEnd":136,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/v3/crates/graphql/graphql-ws/src/websocket/mod.rs#L100-L136","documentation":"The `Sec-WebSocket-Protocol` header was present but its value could not be interpreted; specifically the header value failed conversion to a string (`ToStrError` from the http crate), usually because it contains non-visible-ASCII bytes. Reported as `WebSocketError::InvalidHeaderValue` during the upgrade handshake.","triggerScenarios":"A client or intermediary sends a Sec-WebSocket-Protocol header value containing bytes outside visible ASCII (control characters, non-ASCII encoding), causing `to_str()` on the header value to fail when the server parses the subprotocol list.","commonSituations":"Malformed handcrafted WS clients; middleware or proxies that mangle header encoding (e.g. UTF-16 leaking in); corrupted header injection in test harnesses; rarely, a badly encoded library default protocol string.","solutions":["Capture the raw upgrade request to inspect the exact Sec-WebSocket-Protocol bytes","Fix the client/intermediary to send a plain ASCII value such as `graphql-transport-ws`","Remove or repair any proxy transform that rewrites the header","If handcrafting handshakes, validate the header is visible-ASCII before sending"],"exampleFix":"# before (curl, accidental raw bytes)\ncurl -H $'Sec-WebSocket-Protocol: graphql-transport-ws\\x0b' ...\n# after\ncurl -H 'Sec-WebSocket-Protocol: graphql-transport-ws' ...","handlingStrategy":"validation","validationCode":"const proto = 'graphql-transport-ws';\nif (!/^[\\x21-\\x7e]+$/.test(proto)) throw new Error('bad protocol header');","typeGuard":null,"tryCatchPattern":"catch (e) { if (String(e).includes('Sec-WebSocket-Protocol')) { inspect raw header bytes; resend with ASCII value; } }","preventionTips":["Send only visible-ASCII subprotocol names","Audit proxies that rewrite header encoding","Dump the raw handshake when debugging"],"tags":["websocket","http-headers","handshake","graphql-ws"],"backgroundTag":"invalid-http-header-value","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}