hasura/graphql-engine · error · BuildRequestError

Failed to convert session variable '{variable_name}': {error

Error message

Failed to convert session variable '{variable_name}': {error}

What it means

A single named session variable could not be converted while preparing the pre-NDC-response plugin request; the variable name and the serde error are both included. The variable exists in the session but its value does not fit the target type in the hook wire format.

Source

Thrown at v3/crates/plugins/pre-ndc-response-plugin/src/execute.rs:54

}

#[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(_, _)
            | Error::UnexpectedStatusCode(_)
            | Error::PluginInternalError { .. } => ErrorVisibility::User,

View on GitHub (pinned to 724551b9ae)

Solutions

1. Inspect the named variable's value in the token/session and its expected type
2. Correct the claim shape in the IdP or update the plugin config
3. Drop the variable from forwarding if unused
4. Re-test after auth configuration changes

// check claim type matches the forwarded type
assert!(matches!(claims.get(var), Some(Value::String(_))));

if let Err(Error::SessionVariableConversionError { variable_name, error }) = res {
    tracing::warn!(variable_name, ?error, "variable conversion failed");
}

When it happens

Trigger: A configured session variable's JSON value (object/array where a scalar is expected, or vice versa) fails conversion in build_request for the response hook.

Common situations: IdP changing a claim's type (string → array) after an update; stale plugin config referencing old claim names; nested objects forwarded where strings are expected.

Related errors

• Failed to convert session variable '{variable_name}': {error
• Failed to convert session: {0}
• Failed to convert session: {0}
• Serde error: {error}
• Serialization error: {0}

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