{"record":{"id":"f251b9c57a325954","repo":"hasura/graphql-engine","slug":"required-session-variable-not-found-in-the-request","errorCode":null,"errorMessage":"Required session variable not found in the request: {session_variable}","messagePattern":"Required session variable not found in the request: (.+?)","errorType":"exception","errorClass":"InternalDeveloperError::MissingSessionVariable","httpStatus":null,"severity":"error","filePath":"v3/crates/plan/src/error.rs","lineNumber":33,"sourceCode":"pub enum InternalError {\n    #[error(\"{0}\")]\n    Developer(#[from] InternalDeveloperError),\n    #[error(\"{0}\")]\n    Engine(#[from] InternalEngineError),\n}\n\nimpl TraceableError for InternalError {\n    fn visibility(&self) -> ErrorVisibility {\n        match self {\n            Self::Developer(error) => error.visibility(),\n            Self::Engine(_) => ErrorVisibility::Internal,\n        }\n    }\n}\n\n#[derive(Debug, thiserror::Error)]\npub enum InternalDeveloperError {\n    #[error(\"Required session variable not found in the request: {session_variable}\")]\n    MissingSessionVariable {\n        session_variable: SessionVariableName,\n    },\n\n    #[error(\n        \"The session variables {session_variable} is not encoded as a string. JSON-typed session variables are not supported unless you update your compatibility date\"\n    )]\n    VariableJsonNotSupported {\n        session_variable: SessionVariableName,\n    },\n\n    #[error(\n        \"Session variable {session_variable} value is of an unexpected type. Expected: {expected}, but found: {found}\"\n    )]\n    VariableTypeCast {\n        session_variable: SessionVariableName,\n        expected: String,\n        found: String,","sourceCodeStart":15,"sourceCodeEnd":51,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/v3/crates/plan/src/error.rs#L15-L51","documentation":"Internal developer error from the plan crate: a session variable referenced in the query (e.g. in an argument preset or expression) was required but was not present in the incoming request's session variables (e.g. Hasura request headers like x-hasura-user-id).","triggerScenarios":"Executing a planned query whose expression tree contains a SessionVariable reference and the request's session variable set does not contain that key; happens when building NDC queries with argument presets bound to x-hasura-* variables.","commonSituations":"Testing a query in an environment where auth headers are absent (curl without x-hasura-user-id); renaming a preset's session variable without updating clients; admin/CI bypass that strips headers.","solutions":["Send the missing session variable as a request header (x-hasura-<name>) or via the session_variables field of the request","If the variable is optional, give the expression a fallback/default so it is not required","Check the argument preset / permission rule that references the variable and confirm the exact variable name clients must send"],"exampleFix":"# before\ncurl .../graphql -d '{ user(id: 1) { ... } }'   # preset needs x-hasura-user-id\n# after\ncurl .../graphql -H 'x-hasura-user-id: 1' -d '{ user(id: 1) { ... } }'","handlingStrategy":"validation","validationCode":"// Before executing, ensure every required session variable is present\nfor var in plan.required_session_variables() {\n    request.session_variables\n        .get(var)\n        .ok_or_else(|| format!(\"missing session variable: {var}\"))?;\n}","typeGuard":"fn has_all_session_vars(req: &Request, vars: &[&str]) -> bool {\n    vars.iter().all(|v| req.session_variables.contains_key(*v))\n}","tryCatchPattern":"match plan.execute(req) {\n    Err(InternalDeveloperError::MissingSessionVariable { session_variable }) => {\n        // ask the client to send x-hasura-<name>\n    }\n    r => r,\n}","preventionTips":["Document required x-hasura-* headers per query in client SDKs","Default optional presets so requests succeed without auth headers in dev"],"tags":["session-variables","auth","plan","hasura"],"backgroundTag":"missing-session-variable","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}