hasura/graphql-engine · error · InternalDeveloperError::VariableJsonNotSupported

The session variables {session_variable} is not encoded as a

Error message

The session variables {session_variable} is not encoded as a string. JSON-typed session variables are not supported unless you update your compatibility date

What it means

The plan crate received a session variable whose value is a JSON object/array rather than a plain string, but the project's compatibility date is older than JSON session variable support, so only string-encoded values are allowed.

Source

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

}

impl TraceableError for InternalError {
    fn visibility(&self) -> ErrorVisibility {
        match self {
            Self::Developer(error) => error.visibility(),
            Self::Engine(_) => ErrorVisibility::Internal,
        }
    }
}

#[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"
    )]

View on GitHub (pinned to 724551b9ae)

Solutions

1. Update the project's compatibility date to one that enables JSON session variables
2. Or send session variables as plain string values (headers) as the older protocol expects
3. Align client SDK version with the engine/compatibility date

Example fix

# before
compatibility_date: "2024-01-01"  # before JSON session var support
# after
compatibility_date: "2025-01-01"  # enables JSON session variables

// Only send JSON-encoded session variables when compatibility date allows it
let allow_json = compatibility_date >= JSON_SESSION_VARS_DATE;
if !allow_json { send_session_vars_as_strings(&mut request); }

match err {
    InternalDeveloperError::VariableJsonNotSupported { session_variable } => {
        // resend the variable as a plain string value
    }
    _ => {}
}

When it happens

Trigger: A request sends a session variable as a JSON value (object/array) via a bulk/JSON transport while the engine's compatibility date predates the JSON-session-variables feature; typecasting or reading that variable then fails with this error.

Common situations: Clients migrated to a newer protocol that JSON-encodes session variables while the project still pins an old compatibility date; copying newer example requests into an older project.

Related errors

• Typecasting session variable {session_variable} to an array
• Session variable not found: {name}
• Required session variable not found in the request: {session
• Session variable {session_variable} value is of an unexpecte
• 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/f155ad6f184aa30a. Report an issue: GitHub.