{"record":{"id":"8d759b7e78daa1b6","repo":"hasura/graphql-engine","slug":"expected-string-value-for-claim-claim-name","errorCode":null,"errorMessage":"Expected string value for claim {claim_name}","messagePattern":"Expected string value for claim (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"v3/crates/auth/hasura-authn-jwt/src/jwt.rs","lineNumber":44,"sourceCode":"\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 },\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}\")]","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/v3/crates/auth/hasura-authn-jwt/src/jwt.rs#L26-L62","documentation":"The claims map indicates a claim should be a string (or a string is required for further processing), but the JWT contains a non-string value (object, number, array, boolean) for that claim.","triggerScenarios":"Extracting Hasura roles or other configured claims where the configured claim path resolves to a non-string JSON value, e.g. `\"default-role\": 42` instead of `\"default-role\": \"user\"`.","commonSituations":"Auth provider issues numeric or structured claims where strings are expected; metadata config assumes a string type that the IdP does not emit.","solutions":["Decode the token and check the JSON type of {claim_name}","Ensure the token issuer emits the claim as a string (e.g. quote roles/IDs in the JWT payload)","Adjust the claims map configuration to point at a claim that is actually a string"],"exampleFix":"// before (JWT payload)\n{ \"https://hasura.io/jwt/claims\": { \"default-role\": \"user\", \"x-claim\": 123 } }\n// after\n{ \"https://hasura.io/jwt/claims\": { \"default-role\": \"user\", \"x-claim\": \"123\" } }","handlingStrategy":"type-guard","validationCode":"const payload = decodeJwt(token);\nfor (const name of requiredStringClaims) {\n  if (typeof payload[name] !== 'string') return reject('claim ' + name + ' must be a string');\n}","typeGuard":"const isString = (v: unknown): v is string => typeof v === 'string';","tryCatchPattern":"Map the error to a 401 with a message naming the offending claim; prompt token refresh.","preventionTips":["Ensure the IdP custom-claims template emits strings (quote numbers)","Add contract tests on issued tokens"],"tags":["jwt","claims","type-mismatch","auth"],"backgroundTag":"jwt-claim-validation-failed","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}