hasura/graphql-engine · error · InternalDeveloperError

Typecasting session variable {session_variable} to an array

Error message

Typecasting session variable {session_variable} to an array is not supported. Update your compatibility date to enable JSON session variables

What it means

The plan crate was asked to typecast a session variable to an array, but the project's compatibility date does not include JSON session variable support, so non-string (array) session variables cannot be produced.

Source

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

    },

    #[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}"
    )]
    VariableExpectedJson {
        session_variable: SessionVariableName,
        parse_error: serde_json::Error,
    },

    #[error("Type mapping not found for the type name {type_name:}")]
    TypeMappingNotFound {
        type_name: Qualified<CustomTypeName>,
    },

View on GitHub (pinned to 724551b9ae)

Solutions

1. Update the compatibility date so JSON session variables (and array casts) are enabled
2. Or replace the array session variable with a string-encoded value parsed elsewhere
3. Or stop casting that variable to an array and derive the array inside the query instead

Example fix

# before
compatibility_date: "2024-01-01"   # preset casts session var to array
# after
compatibility_date: "2025-01-01"   # array casts of session vars allowed

// Guard array casts behind a feature check before building the query
if expr_casts_session_var_to_array(&plan) && compatibility_date < JSON_SESSION_VARS_DATE {
    return Err("array cast of session variable requires newer compatibility date");
}

match err {
    InternalDeveloperError::VariableArrayTypeCastNotSupported { .. } => {
        // bump compatibility date or string-encode the value
    }
    _ => {}
}

When it happens

Trigger: An expression contains a cast of a session variable to an array type while running with an older compatibility date; the cast is rejected before execution.

Common situations: Using array-typed presets fed by session variables on a project created before JSON session variables existed; upgrading the engine but keeping the old compatibility date constant.

Related errors

• The session variables {session_variable} is not encoded as a
• Session variable {session_variable} value is of an unexpecte
• Session variable not found: {name}
• Required session variable not found in the request: {session
• 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/6d01b17b9941b102. Report an issue: GitHub.