hasura/graphql-engine · error · Error

Error in parsing the {header_name} header: {err}

Error message

Error in parsing the {header_name} header: {err}

What it means

The header named `{header_name}` could not be parsed as expected while extracting the JWT; the raw parse error is included. Typically this covers malformed Authorization headers, e.g. missing the `Bearer ` prefix or containing invalid characters.

Source

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

    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 },
    #[error("Error in parsing the Cookie header value: {err}")]
    CookieParseError { err: cookie::ParseError },
    #[error("Missing corresponding value for the cookie with cookie name: {cookie_name}")]
    MissingCookieValue { cookie_name: String },
    #[error("JWT validation error: {0}")]
    JWTValidationError(jwt::errors::Error),
    #[error("Internal Error - {0}")]
    Internal(#[from] InternalError),
}

impl TraceableError for Error {
    fn visibility(&self) -> ErrorVisibility {
        // For the purpose of traces, all JWT errors should be developer facing.
        ErrorVisibility::User
    }
}

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check {err} and {header_name} to see exactly what failed
2. Ensure the client sends `Authorization: Bearer <token>` (or the configured scheme)
3. Verify no proxy mutates or re-encodes the header

Example fix

// before
Authorization: eyJhbGciOi...
// after
Authorization: Bearer eyJhbGciOi...

const h = req.headers.get('authorization') ?? '';
if (!/^Bearer \S+$/.test(h)) return unauthorized('malformed Authorization header');

const isBearerHeader = (h: string | null): h is `Bearer ${string}` => !!h && /^Bearer \S+$/.test(h);

Return 401 without retry; log the parse error to spot proxy interference.

When it happens

Trigger: Header-based JWT extraction where the Authorization header is present but malformed: no Bearer scheme, stray whitespace, or a value that fails to convert to a string.

Common situations: Client sends the raw token without `Bearer `; custom auth scheme mismatch; proxies rewriting the Authorization header.

Related errors

• Session variable not found: {name}
• JWT Authorization token source: Header name {header_name} no
• Serde error: {error}
• Condition {condition_hash} not found
• Expected array or null for right-hand value of contains oper

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