hasura/graphql-engine · error · InternalDeveloperError

Expected session variable {session_variable} to be a valid J

Error message

Expected session variable {session_variable} to be a valid JSON value, but encountered a JSON parsing error: {parse_error}

What it means

A session variable was expected to contain valid JSON (because it is used as a JSON value, e.g. cast to an array/object), but parsing it as JSON failed. The underlying serde_json parse error is included.

Source

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

    },

    #[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>,
    },

    #[error("Field mapping not found for the field {field_name:} of type {type_name:}")]
    FieldMappingNotFound {
        type_name: Qualified<CustomTypeName>,
        field_name: FieldName,
    },

View on GitHub (pinned to 724551b9ae)

Solutions

1. Fix the client/auth layer to send a syntactically valid JSON value for that variable (quote strings, bracket arrays)
2. Validate the variable server-side before the request (auth webhook) with a JSON parse check
3. If JSON isn't actually needed, remove the JSON/cast usage and treat it as a plain string

Example fix

# before
x-hasura-roles: admin,user
# after
x-hasura-roles: ["admin","user"]

// Client-side: ensure JSON-typed session variables parse
let v: serde_json::Value = serde_json::from_str(raw).map_err(|e| format!("invalid JSON: {e}"))?;

match err {
    InternalDeveloperError::VariableExpectedJson { session_variable, parse_error } => {
        eprintln!("{session_variable} must be valid JSON: {parse_error}");
    }
    _ => {}
}

When it happens

Trigger: Casting or consuming a session variable as a JSON value where the raw string is not valid JSON — e.g. x-hasura-roles containing 'admin;user' instead of '["admin","user"]'.

Common situations: Header-encoded lists using commas/semicolons instead of JSON arrays; truncated or quoted-wrong values from auth webhooks; clients not updated after a preset switched to JSON format.

Related errors

• parse file %w
• failed parsing json: %w; response from API: %s
• reading metadata file: %w
• Session variable not found: {name}
• {error} at path {path}

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