hasura/graphql-engine · error · InternalDeveloperError

Session variable {session_variable} value is of an unexpecte

Error message

Session variable {session_variable} value is of an unexpected type. Expected: {expected}, but found: {found}

What it means

A session variable value could not be interpreted as the expected type during typecasting in the plan crate. The error names the variable, the expected type, and what was actually found (e.g. expected 'integer', found 'boolean').

Source

Thrown at v3/crates/plan/src/error.rs:45

        }
    }
}

#[derive(Debug, thiserror::Error)]
pub enum InternalDeveloperError {
    #[error("Required session variable not found in the request: {session_variable}")]
    MissingSessionVariable {
        session_variable: SessionVariableName,
    },

    #[error(
        "The session variables {session_variable} is not encoded as a string. JSON-typed session variables are not supported unless you update your compatibility date"
    )]
    VariableJsonNotSupported {
        session_variable: SessionVariableName,
    },

    #[error(
        "Session variable {session_variable} value is of an unexpected type. Expected: {expected}, but found: {found}"
    )]
    VariableTypeCast {
        session_variable: SessionVariableName,
        expected: String,
        found: String,
    },

    #[error(
        "Typecasting session variable {session_variable} to an array is not supported. Update your compatibility date to enable JSON session variables"
    )]
    VariableArrayTypeCastNotSupported {
        session_variable: SessionVariableName,
    },

    #[error(
        "Expected session variable {session_variable} to be a valid JSON value, but encountered a JSON parsing error: {parse_error}"
    )]

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check the expected/found pair in the message and fix the client to send a value matching the expected type
2. Adjust the cast target type in the preset/expression to match the actual variable format
3. If the variable arrives as JSON, ensure the compatibility date and transport support it and that a scalar (not array/object) is provided

Example fix

# before
# preset: count = session(x-hasura-count) :: integer  (client sends "true")
# after
# client sends: x-hasura-count: 42

// Pre-validate a castable value on the client
fn parses_as(value: &str, ty: &str) -> bool {
    match ty {
        "integer" => value.parse::<i64>().is_ok(),
        "float" => value.parse::<f64>().is_ok(),
        "boolean" => value == "true" || value == "false",
        _ => true,
    }
}

match err {
    InternalDeveloperError::VariableTypeCast { session_variable, expected, found } => {
        eprintln!("{session_variable}: send {expected}, got {found}");
    }
    _ => {}
}

When it happens

Trigger: Typecasting a session variable (session_variable cast in an expression/preset) where the raw string/JSON value does not parse as the declared target type — e.g. x-hasura-role used as an integer, or a JSON array where a scalar was expected once JSON vars are enabled.

Common situations: Clients sending unquoted numbers/booleans in headers; presets casting x-hasura-* headers to int/float/date; mismatch between declared scalar type and what the auth webhook/JWT claim provides.

Related errors

• Required session variable not found in the request: {session
• Typecasting session variable {session_variable} to an array
• Session variable not found: {name}
• The session variables {session_variable} is not encoded as a
• Expected session variable {session_variable} to be a valid J

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