{"record":{"id":"23773575c9abf0ed","repo":"mastra-ai/mastra","slug":"invalid-token-header","errorCode":null,"errorMessage":"Invalid token header","messagePattern":"Invalid token header","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/auth/src/utils.ts","lineNumber":14,"sourceCode":"import jwt from 'jsonwebtoken';\nimport jwksClient from 'jwks-rsa';\n\nexport type JwtPayload = jwt.JwtPayload;\n\nexport async function decodeToken(accessToken: string) {\n  const decoded = jwt.decode(accessToken, { complete: true });\n  return decoded;\n}\n\nexport function getTokenIssuer(decoded: jwt.JwtPayload | null) {\n  if (!decoded) throw new Error('Invalid token');\n  if (!decoded.payload || typeof decoded.payload !== 'object') throw new Error('Invalid token payload');\n  if (!decoded.payload.iss) throw new Error('Invalid token header');\n  return decoded.payload.iss;\n}\n\nexport async function verifyHmac(accessToken: string, secret: string) {\n  const decoded = jwt.decode(accessToken, { complete: true });\n\n  if (!decoded) throw new Error('Invalid token');\n\n  return jwt.verify(accessToken, secret) as jwt.JwtPayload;\n}\n\nexport async function verifyJwks(accessToken: string, jwksUri: string) {\n  const decoded = jwt.decode(accessToken, { complete: true });\n\n  if (!decoded) throw new Error('Invalid token');\n\n  const client = jwksClient({ jwksUri });\n  const key = await client.getSigningKey(decoded.header.kid);","sourceCodeStart":1,"sourceCodeEnd":32,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/auth/src/utils.ts#L1-L32","documentation":"getTokenIssuer decodes a JWT and returns its `iss` (issuer) claim. This error is thrown when the payload decodes to an object but has no truthy `iss` claim. Despite the message saying 'header', the check is `!decoded.payload.iss` — the token lacks the issuer claim the library relies on to route issuer-specific verification.","triggerScenarios":"Calling getTokenIssuer(accessToken) on a validly decoded JWT whose payload is an object but has no `iss` property (or iss is empty/null), so `decoded.payload.iss` is falsy.","commonSituations":"Tokens issued by providers that omit `iss` (opaque or first-party tokens), custom-signed internal tokens missing the issuer claim, or testing with self-minted tokens that don't follow OIDC conventions.","solutions":["Ensure your auth provider includes the `iss` claim in access tokens (enable issuer/audience settings, e.g. Auth0 'Add claims' or API authorization settings)","Decode the token and check `jwt.decode(token, { complete: true }).payload.iss` before calling","If using self-issued tokens, add `iss` to the sign payload","Verify you are passing the access token, not an opaque ID token variant without issuer"],"exampleFix":"// before\njwt.sign({ sub: 'user-1' }, secret); // no iss claim\n// after\njwt.sign({ sub: 'user-1', iss: 'https://your-issuer.example.com' }, secret);","handlingStrategy":"validation","validationCode":"function hasIssuerClaim(token: string): boolean {\n  try {\n    const payload = JSON.parse(Buffer.from(token.split('.')[1] ?? '', 'base64url').toString('utf8'));\n    return typeof payload === 'object' && payload !== null && typeof (payload as any).iss === 'string' && (payload as any).iss.length > 0;\n  } catch {\n    return false;\n  }\n}","typeGuard":"function hasIss(decoded: jwt.JwtPayload | null): decoded is jwt.JwtPayload & { iss: string } {\n  return decoded !== null && typeof decoded.iss === 'string' && decoded.iss.length > 0;\n}","tryCatchPattern":"try {\n  const issuer = getTokenIssuer(token);\n} catch (e) {\n  if (e instanceof Error && e.message === 'Invalid token header') {\n    // token has no iss claim: token not usable for issuer-based verification; re-issue with iss\n  }\n  throw e;\n}","preventionTips":["Enable the issuer claim in your auth provider's token settings (OIDC-compliant tokens include iss)","When minting your own tokens, always include iss matching your configured issuer URL","Unit-test that real tokens from your provider contain iss"],"tags":["jwt","auth","missing-claim","issuer"],"backgroundTag":"jwt-missing-iss-claim","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}