{"record":{"id":"c512623af8b935cf","repo":"hasura/graphql-engine","slug":"required-claim-claim-name-not-found","errorCode":null,"errorMessage":"Required claim {claim_name} not found","messagePattern":"Required claim (.+?) not found","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/crates/auth/hasura-authn-jwt/src/jwt.rs","lineNumber":46,"sourceCode":"pub enum Error {\n    #[error(\"Error decoding the `Authorization` header - {0}\")]\n    ErrorDecodingAuthorizationHeader(jwt::errors::Error),\n    #[error(\"`kid` (Key ID) header claim not found in the header\")]\n    KidHeaderNotFound,\n    #[error(\"Expected the Hasura claims to be a String when `claimsFormat` is `stringifiedJson`\")]\n    ExpectedStringifiedJson,\n    #[error(\"The default role is not present in the allowed roles\")]\n    DisallowedDefaultRole,\n    #[error(\"The specified role is not present in the allowed roles\")]\n    DisallowedRole,\n    #[error(\"Error while parsing the claims map entry: {claim_name} - {err}\")]\n    ParseClaimsMapEntryError {\n        claim_name: String,\n        err: serde_json::Error,\n    },\n    #[error(\"Expected string value for claim {claim_name}\")]\n    ClaimMustBeAString { claim_name: String },\n    #[error(\"Required claim {claim_name} not found\")]\n    RequiredClaimNotFound { claim_name: String },\n    #[error(\"JWT Authorization token source: Header name {header_name} not found.\")]\n    AuthorizationHeaderSourceNotFound { header_name: String },\n    #[error(\"JWT Authorization token source: Cookie header not found\")]\n    CookieNotFound,\n    #[error(\n        \"JWT Authorization token source: cookie name {cookie_name} not found in the Cookie header\"\n    )]\n    CookieNameNotFound { cookie_name: String },\n    #[error(\"Error in parsing the {header_name} header: {err}\")]\n    AuthorizationHeaderParseError { err: String, header_name: String },\n    #[error(\"Error in parsing the Cookie header value: {err}\")]\n    CookieParseError { err: cookie::ParseError },\n    #[error(\"Missing corresponding value for the cookie with cookie name: {cookie_name}\")]\n    MissingCookieValue { cookie_name: String },\n    #[error(\"JWT validation error: {0}\")]\n    JWTValidationError(jwt::errors::Error),\n    #[error(\"Internal Error - {0}\")]","sourceCodeStart":28,"sourceCodeEnd":64,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/v3/crates/auth/hasura-authn-jwt/src/jwt.rs#L28-L64","documentation":"A claim declared as required (via the claims map or required-claims configuration) is absent from the verified JWT payload.","triggerScenarios":"JWT validation succeeds cryptographically but the token payload lacks a claim listed in the claims map, e.g. missing `https://hasura.io/jwt/claims` namespace or missing default-role claim.","commonSituations":"Misconfigured JWT namespace in metadata vs. what the IdP emits; custom auth server forgets to include Hasura claims; using a token intended for a different audience/application.","solutions":["Decode the JWT and confirm whether {claim_name} is present","Fix the claims map / namespace configuration to match the token's actual claim names","Update the auth server to include the required claim in issued tokens","Check you are using the correct token (not a refresh token or a token from another app)"],"exampleFix":"// before: claims_map expects \"hasura-claims\"\n// after: claims_map expects \"https://hasura.io/jwt/claims\" (matching the issued token)","handlingStrategy":"validation","validationCode":"const payload = decodeJwt(token);\nconst missing = requiredClaims.filter(c => !(c in payload));\nif (missing.length) return reject('missing claims: ' + missing.join(','));","typeGuard":"const hasClaim = (p: object, c: string): c is keyof typeof p => c in p;","tryCatchPattern":"Catch and return 401 with the missing claim name; instruct the user to log in again.","preventionTips":["Configure the IdP to always embed Hasura claims","Test tokens from each auth flow before rollout"],"tags":["jwt","claims","missing-claim","auth"],"backgroundTag":"jwt-required-claim-missing","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}