{"record":{"id":"47ae2b29a73e896d","repo":"hasura/graphql-engine","slug":"error-while-parsing-the-claims-map-entry-claim-n","errorCode":null,"errorMessage":"Error while parsing the claims map entry: {claim_name} - {err}","messagePattern":"Error while parsing the claims map entry: (.+?) - (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/crates/auth/hasura-authn-jwt/src/jwt.rs","lineNumber":39,"sourceCode":"use url::Url;\n\n/// Name of the key, which is by default used to lookup the Hasura claims\n/// in the claims obtained after decoding the JWT.\npub(crate) const DEFAULT_HASURA_CLAIMS_NAMESPACE: &str = \"claims.jwt.hasura.io\";\n\n#[derive(Debug, thiserror::Error)]\npub 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 },","sourceCodeStart":21,"sourceCodeEnd":57,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/v3/crates/auth/hasura-authn-jwt/src/jwt.rs#L21-L57","documentation":"Thrown when a JWT claim mapped via the claims map (e.g. Hasura claims or other mapped claims) fails to deserialize into the expected type. The `claim_name` identifies which entry in the claims map failed and `err` is the underlying serde_json error describing the exact deserialization problem.","triggerScenarios":"Calling JWT validation/role extraction with a claims map configured, where the token contains a claim whose JSON structure does not match the expected type (e.g. an object where a string is expected, or malformed JSON in a stringified claim).","commonSituations":"Mismatch between the configured claims map in Hasura metadata and the actual JWT payload shape issued by the auth provider; auth provider changes claim formats; stringified JSON claims that contain invalid JSON.","solutions":["Inspect the {claim_name} and {err} fields to identify which claim failed and why","Decode the JWT (e.g. jwt.io or jwt-decode) and compare the actual claim type to your claims map configuration","Update the claims map config or the token issuer so the claim type matches","If using claimsFormat stringifiedJson, verify the claim value is valid JSON"],"exampleFix":"// before\nclaims_map: { \"hasura\": \"https://hasura.io/jwt/claims\" } // token has hasura as object, config expects string\n// after\nclaims_map: { \"hasura\": \"$.https://hasura.io/jwt/claims\" } // or align with actual token structure","handlingStrategy":"validation","validationCode":"// Before validating, decode payload and try deserializing each mapped claim\nconst payload = JSON.parse(atob(token.split('.')[1]));\nfor (const [name, path] of Object.entries(claimsMap)) {\n  const v = resolvePath(payload, path);\n  if (v === undefined) throw new Error(`claim ${name} missing`);\n  JSON.stringify(v); // ensure serializable/expected shape\n}","typeGuard":"function isStringClaim(v: unknown): v is string { return typeof v === 'string'; }","tryCatchPattern":"Catch the auth error and surface claim_name/err to the client as 'invalid token claims'; do not retry — the token must be reissued.","preventionTips":["Validate claim shapes in a test that decodes a sample production token","Keep claims map config in sync with the IdP token contract"],"tags":["jwt","claims","deserialization","auth"],"backgroundTag":"jwt-claim-validation-failed","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}