hasura/graphql-engine · error · ConnectionInitError

SessionError: {0}

Error message

SessionError: {0}

What it means

This wraps a `SessionError` raised while handling a `connection_init` message, meaning session creation or validation failed during connection setup. The graphql-ws layer delegates session establishment to a session subsystem and surfaces its failures through `ConnectionInitError::Session`.

Source

Thrown at v3/crates/graphql/graphql-ws/src/protocol/init.rs:128

                    }
                })
            },
        )
        .await
}

/// Error types that may occur during connection initialization.
#[derive(Debug, thiserror::Error)]
pub enum ConnectionInitError {
    #[error("Connection already initialized")]
    AlreadyInitialized,
    #[error("Invalid header name: {0}")]
    InvalidHeaderName(#[from] http::header::InvalidHeaderName),
    #[error("Invalid header value: {0}")]
    InvalidHeaderValue(#[from] http::header::InvalidHeaderValue),
    #[error("AuthError: {0}")]
    Authn(#[from] AuthError),
    #[error("SessionError: {0}")]
    Session(#[from] SessionError),
}

impl tracing_util::TraceableError for ConnectionInitError {
    fn visibility(&self) -> tracing_util::ErrorVisibility {
        tracing_util::ErrorVisibility::User
    }
}

/// Parses headers from a given map of strings into an `http::HeaderMap`.
/// Returns a parsed header map or an error if the headers are invalid.
fn parse_headers(map: HashMap<String, String>) -> Result<http::HeaderMap, ConnectionInitError> {
    let mut headers = http::HeaderMap::new();
    for (key, value) in map {
        let header_name = http::HeaderName::from_bytes(key.as_bytes())?;
        let header_value = http::HeaderValue::from_str(&value)?;
        headers.insert(header_name, header_value);
    }

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check the health/connectivity of the session store backing the connection
2. Inspect the connection_init payload for session-related parameters and correct them
3. Look for and raise session concurrency limits if the server reports exhaustion
4. Check server logs for the underlying SessionError variant for a precise cause

catch (e) { if (String(e).startsWith('SessionError:')) { await delay(backoff()); reconnect(); } }

When it happens

Trigger: The connection-init flow attempts to create or attach to a session and the session layer fails — e.g. session store unavailable, invalid session parameters in the payload, or session limits exceeded.

Common situations: Session store (e.g. Redis or in-memory store) down or unreachable; too many concurrent sessions hitting a configured cap; session-related payload parameters malformed after a protocol version change.

Related errors

• AuthError: {0}
• Connection already initialized
• Invalid header value: {0}
• graphql-ws protocol is not initialized
• Missing {SEC_WEBSOCKET_PROTOCOL} header

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/9310e35a0eaf3cc4. Report an issue: GitHub.