hasura/graphql-engine · error · Error

Error while parsing the claims map entry: {claim_name} - {er

Error message

Error while parsing the claims map entry: {claim_name} - {err}

What it means

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.

Source

Thrown at v3/crates/auth/hasura-authn-jwt/src/jwt.rs:39

use url::Url;

/// Name of the key, which is by default used to lookup the Hasura claims
/// in the claims obtained after decoding the JWT.
pub(crate) const DEFAULT_HASURA_CLAIMS_NAMESPACE: &str = "claims.jwt.hasura.io";

#[derive(Debug, thiserror::Error)]
pub enum Error {
    #[error("Error decoding the `Authorization` header - {0}")]
    ErrorDecodingAuthorizationHeader(jwt::errors::Error),
    #[error("`kid` (Key ID) header claim not found in the header")]
    KidHeaderNotFound,
    #[error("Expected the Hasura claims to be a String when `claimsFormat` is `stringifiedJson`")]
    ExpectedStringifiedJson,
    #[error("The default role is not present in the allowed roles")]
    DisallowedDefaultRole,
    #[error("The specified role is not present in the allowed roles")]
    DisallowedRole,
    #[error("Error while parsing the claims map entry: {claim_name} - {err}")]
    ParseClaimsMapEntryError {
        claim_name: String,
        err: serde_json::Error,
    },
    #[error("Expected string value for claim {claim_name}")]
    ClaimMustBeAString { claim_name: String },
    #[error("Required claim {claim_name} not found")]
    RequiredClaimNotFound { claim_name: String },
    #[error("JWT Authorization token source: Header name {header_name} not found.")]
    AuthorizationHeaderSourceNotFound { header_name: String },
    #[error("JWT Authorization token source: Cookie header not found")]
    CookieNotFound,
    #[error(
        "JWT Authorization token source: cookie name {cookie_name} not found in the Cookie header"
    )]
    CookieNameNotFound { cookie_name: String },
    #[error("Error in parsing the {header_name} header: {err}")]
    AuthorizationHeaderParseError { err: String, header_name: String },

View on GitHub (pinned to 724551b9ae)

Solutions

1. Inspect the {claim_name} and {err} fields to identify which claim failed and why
2. Decode the JWT (e.g. jwt.io or jwt-decode) and compare the actual claim type to your claims map configuration
3. Update the claims map config or the token issuer so the claim type matches
4. If using claimsFormat stringifiedJson, verify the claim value is valid JSON

Example fix

// before
claims_map: { "hasura": "https://hasura.io/jwt/claims" } // token has hasura as object, config expects string
// after
claims_map: { "hasura": "$.https://hasura.io/jwt/claims" } // or align with actual token structure

// Before validating, decode payload and try deserializing each mapped claim
const payload = JSON.parse(atob(token.split('.')[1]));
for (const [name, path] of Object.entries(claimsMap)) {
  const v = resolvePath(payload, path);
  if (v === undefined) throw new Error(`claim ${name} missing`);
  JSON.stringify(v); // ensure serializable/expected shape
}

function isStringClaim(v: unknown): v is string { return typeof v === 'string'; }

Catch the auth error and surface claim_name/err to the client as 'invalid token claims'; do not retry — the token must be reissued.

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Expected string value for claim {claim_name}
• Required claim {claim_name} not found
• Session variable not found: {name}
• Serde error: {error}
• JWT Authorization token source: Header name {header_name} no

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