hasura/graphql-engine · error · ConditionError

Session variable not found: {name}

Error message

Session variable not found: {name}

What it means

Part of the authorization ConditionError enum in Hasura DD Nexus: while evaluating a role-based permission condition (model/command filter), the engine needs to substitute a session variable into the condition, but no such variable is present in the request's session context (claims from JWT/webhook auth).

Source

Thrown at v3/crates/auth/authorization-rules/src/condition.rs:15

//! this is where we evaluate Conditions

use std::fmt::Display;

use hasura_authn_core::{SessionVariableName, SessionVariables};

use crate::ConditionCache;
use metadata_resolve::{
    BinaryOperation, Condition, ConditionHash, Conditions, UnaryOperation, ValueExpression,
};
use open_dds::query::ArgumentName;

#[derive(Debug, PartialEq, Eq, thiserror::Error)]
pub enum ConditionError {
    #[error("Session variable not found: {name}")]
    SessionVariableNotFound { name: SessionVariableName },
    #[error("Serde error: {error}")]
    SerdeError { error: String },
    #[error("Condition {condition_hash} not found")]
    ConditionNotFound { condition_hash: ConditionHash },
    #[error("Expected array or null for right-hand value of contains operation")]
    ExpectedArrayOrNullForContains,
    #[error("Expected number for {side}-hand value of comparison operation")]
    ExpectedNumberForComparison { side: Side },
    #[error(
        "Number for {side}-hand value of comparison operation is outside precision or range of a double-precision float"
    )]
    NumberOutOfRange { side: Side },
    #[error(
        "Tried to combine a predicate with a literal in argument presets for argument {argument_name}"
    )]
    CouldNotCombinePredicateAndLiteralArgumentPresets { argument_name: ArgumentName },
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Inspect the decoded JWT (or webhook response) and confirm the claim matching the session variable exists (e.g. `x-hasura-user-id` maps to `x_hasura_user_id`)
2. Fix the auth server/token to include the required claim
3. Correct the session variable name in the role's comparison expression / permission rule
4. Grant an unauthenticated role for requests without claims if that is intended

Example fix

# before: JWT lacks the claim
{ "sub": "user1" }
# after
{ "sub": "user1", "https://hasura.io/jwt/claims": { "x-hasura-user-id": "user1" } }

const claims = decodeJwtClaims(token);
const required = Object.keys(rule.sessionVars ?? {});
const missing = required.filter(v => !(v in claims));
if (missing.length) throw new Error(`Missing session variables: ${missing.join(', ')}`);

const hasSessionVariable = (claims: Record<string, unknown>, name: string): boolean => Object.prototype.hasOwnProperty.call(claims, name);

null

When it happens

Trigger: A permission rule referencing a session variable like `x_hasura_user_id` when the JWT/webhook for the current request does not contain that claim — e.g. logging in with a token from a different auth flow, or a typo in the role's comparison_expressions.

Common situations: Auth server stops emitting a claim; role config references a variable name that was renamed; anonymous requests hitting a role that requires user claims; env differences between dev/prod tokens.

Related errors

• Condition {condition_hash} not found
• Expected array or null for right-hand value of contains oper
• Expected number for {side}-hand value of comparison operatio
• Error in parsing the {header_name} header: {err}
• Required session variable not found in the request: {session

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