{"record":{"id":"4898fe50a2b88b55","repo":"hasura/graphql-engine","slug":"connection-initialization-timed-out","errorCode":null,"errorMessage":"Connection initialization timed out","messagePattern":"Connection initialization timed out","errorType":"exception","errorClass":"ConnectionTimeOutError","httpStatus":null,"severity":"error","filePath":"v3/crates/graphql/graphql-ws/src/websocket/tasks.rs","lineNumber":19,"sourceCode":"use super::types;\nuse crate::metrics::WebSocketMetrics;\nuse crate::protocol;\nuse axum::extract::ws;\nuse futures_util::{SinkExt, StreamExt};\nuse tokio::time::{Duration, timeout};\n\n/// Enum to represent whether the loop should continue or break.\n#[derive(PartialEq)]\nenum BreakLoop {\n    /// Indicates the loop should break.\n    Break,\n    /// Indicates the loop should continue.\n    Dont,\n}\n\n/// Error type for connection timeouts during WebSocket initialization.\n#[derive(thiserror::Error, Debug)]\n#[error(\"Connection initialization timed out\")]\npub(crate) struct ConnectionTimeOutError;\n\nimpl tracing_util::TraceableError for ConnectionTimeOutError {\n    fn visibility(&self) -> tracing_util::ErrorVisibility {\n        tracing_util::ErrorVisibility::User\n    }\n}\n\n/// Checks if the graphql-ws protocol is initialized within the specified timeout duration.\n/// Ref: <https://github.com/enisdenjo/graphql-ws/blob/master/PROTOCOL.md#connectioninit>\npub(crate) async fn verify_connection_init<M: Send>(\n    connection: types::Connection<M>,\n    timeout_duration: Duration,\n    parent_span_link: tracing_util::SpanLink,\n) -> Result<(), ConnectionTimeOutError> {\n    let tracer = tracing_util::global_tracer();\n    tracer\n        .new_trace_async_with_link(","sourceCodeStart":1,"sourceCodeEnd":37,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/v3/crates/graphql/graphql-ws/src/websocket/tasks.rs#L1-L37","documentation":"The graphql-ws server starts a timer when a WebSocket connection is opened and expects the client to send the ConnectionInit message within the configured connection initialization window. If no init message arrives in time, the server gives up and reports this timeout error and closes the socket. This protects the server from idle or half-open connections occupying resources.","triggerScenarios":"A client opens the WebSocket but never sends the 'connection_init' message (no payload or a client bug), or network/latency causes it to arrive after the configured connection_init_timeout window elapses.","commonSituations":"Custom WebSocket clients that only subscribe without initializing; heavy startup work on the client delaying the init frame; misconfigured very short connection init timeout on the server; NAT/proxy idle handling delaying the first frame.","solutions":["Ensure your client sends connection_init immediately after the socket opens (graphql-ws clients do this automatically when a payload/callback is provided)","Increase the server's connection init timeout configuration if clients are slow to initialize","Check for intermediaries that delay or buffer the first WebSocket frame"],"exampleFix":"// before (client)\nconst ws = new WebSocket(url, 'graphql-ws');\n// ...subscribe without initializing\n\n// after\nimport { createClient } from 'graphql-ws';\nconst client = createClient({ webSocketImpl: ws, connectionInit: { authorization: token } });","handlingStrategy":"retry","validationCode":"// Ensure connectionInit is provided so the client sends connection_init immediately\nconst client = createClient({ webSocketImpl: ws, connectionInit: {{}} });","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always configure a connectionInit payload/callback in your graphql-ws client","Keep client startup work off the socket-open critical path","Tune server connection_init_timeout above worst-case client startup latency"],"tags":["websocket","graphql","timeout","connection-init","rust"],"backgroundTag":"websocket-connection-init-timeout","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}