hasura/graphql-engine · error · BuildRequestError

Failed to convert session: {0}

Error message

Failed to convert session: {0}

What it means

The engine failed to convert the request's session/authorization object into the simplified map the pre-NDC-request plugin expects, and the string detail explains what part could not be converted. This happens during request building, before any HTTP call to the plugin. It usually stems from an authorization context shape the plugin conversion code does not handle.

Source

Thrown at v3/crates/plugins/pre-ndc-request-plugin/src/execute.rs:52

        error: serde_json::Value,
    },
}

#[derive(Debug, thiserror::Error)]
pub enum BuildRequestError {
    #[error("Invalid header name {header_name}: {error}")]
    InvalidHeaderName {
        header_name: String,
        #[source]
        error: InvalidHeaderName,
    },
    #[error("Invalid header value for header {header_name}: {error}")]
    InvalidHeaderValue {
        header_name: HeaderName,
        #[source]
        error: InvalidHeaderValue,
    },
    #[error("Failed to convert session: {0}")]
    SessionConversionError(String),
    #[error("Failed to convert session variable '{variable_name}': {error}")]
    SessionVariableConversionError {
        variable_name: SessionVariableName,
        error: serde_json::Error,
    },
    #[error("Serialization error: {0}")]
    SerializationError(#[from] serde_json::Error),
}

impl TraceableError for Error {
    fn visibility(&self) -> ErrorVisibility {
        match self {
            Error::BuildRequestError(_, _) => ErrorVisibility::Internal,
            Error::PluginUserError { .. }
            | Error::ReqwestError(_)
            | Error::PluginRequestParseError(_)
            | Error::ErrorWhileMakingHTTPRequestToTheHook(_, _)

View on GitHub (pinned to 724551b9ae)

Solutions

1. Read the {0} detail string — it names the exact session field that failed
2. Compare the JWT claims your IdP issues against the session format the plugin expects
3. Test with a minimal token containing only standard claims to isolate the offending field
4. Update the plugin crate/engine together so session conversion stays in sync

if let Err(Error::SessionConversionError(detail)) = res {
    tracing::error!(detail, "session conversion failed; check auth config");
}

When it happens

Trigger: Calling a query with an auth session whose claims/roles structure cannot be mapped to the plugin's session representation, producing Error::SessionConversionError(detail) in build_request.

Common situations: Switching authentication modes (anonymous → JWT) without updating plugin config; a JWT with unexpected claim nesting; a new role format introduced by an engine upgrade.

Related errors

• Failed to convert session: {0}
• Failed to convert session variable '{variable_name}': {error
• Failed to convert session variable '{variable_name}': {error
• Serde error: {error}
• Condition {condition_hash} not found

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