{"record":{"id":"9146cbd22b031317","repo":"hasura/graphql-engine","slug":"jwt-validation-error-0","errorCode":null,"errorMessage":"JWT validation error: {0}","messagePattern":"JWT validation error: (.+?)","errorType":"exception","errorClass":"Error","httpStatus":400,"severity":"error","filePath":"v3/crates/auth/hasura-authn-jwt/src/jwt.rs","lineNumber":62,"sourceCode":"    #[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}\")]\n    Internal(#[from] InternalError),\n}\n\nimpl TraceableError for Error {\n    fn visibility(&self) -> ErrorVisibility {\n        // For the purpose of traces, all JWT errors should be developer facing.\n        ErrorVisibility::User\n    }\n}\n\n#[derive(Debug, thiserror::Error)]\npub enum InternalError {\n    #[error(\"Error while constructing the JWT decoding key: {0}\")]\n    JWTDecodingKeyError(jwt::errors::Error),\n    #[error(\"Error while decoding the JWT: {0}\")]\n    JWTDecodingError(jwt::errors::Error),","sourceCodeStart":44,"sourceCodeEnd":80,"githubUrl":"https://github.com/hasura/graphql-engine/blob/724551b9ae87845594ef0408cff0e50eb6c90dc5/v3/crates/auth/hasura-authn-jwt/src/jwt.rs#L44-L80","documentation":"Wrapper around the underlying jsonwebtoken crate validation error ({0}). Signals that the token failed cryptographic or claims validation: invalid signature, expired token (exp), not-yet-valid (nbf), wrong issuer/audience, etc.","triggerScenarios":"The token is well-formed and extracted, but fails validation — expired `exp`, signature not matching the configured key/JWKS, `iss`/`aud` mismatch, or malformed token structure.","commonSituations":"Expired tokens after long idle sessions; rotated signing keys with stale JWKS cache; wrong issuer/audience config; clock skew between servers causing premature expiry.","solutions":["Inspect the inner jwt::errors::Error kind (ExpiredSignature / InvalidSignature / InvalidIssuer / InvalidAudience)","Refresh the token if expired and retry with the new token","Verify the JWKS endpoint / configured key matches the issuer and refresh cached keys","Align iss/aud claims in metadata with what the IdP issues; check server clock skew"],"exampleFix":"// before: request with expired token\n// after: refresh access token, then request with new Bearer token","handlingStrategy":"retry","validationCode":"const payload = decodeJwt(token);\nif (payload.exp * 1000 <= Date.now()) await refreshToken();","typeGuard":"const isExpired = (p: { exp?: number }): boolean => (p.exp ?? 0) * 1000 <= Date.now();","tryCatchPattern":"On ExpiredSignature, refresh the token once and retry the request; on InvalidSignature stop and alert (key mismatch is config-level).","preventionTips":["Preemptively refresh tokens before exp","Refresh JWKS cache on UnknownKey kid errors","Align iss/aud config with the IdP"],"tags":["jwt","validation","signature","auth"],"backgroundTag":"jwt-validation-failed","analyzedSha":"724551b9ae87845594ef0408cff0e50eb6c90dc5","analyzedAt":"2026-08-28T07:32:55.105Z","schemaVersion":2},"datasetVersion":"2026-08-28T11:17:15.048Z"}