{"record":{"id":"96ad1db43bf07593","repo":"mastra-ai/mastra","slug":"invalid-token-payload","errorCode":null,"errorMessage":"Invalid token payload","messagePattern":"Invalid token payload","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/auth/src/utils.ts","lineNumber":13,"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 });","sourceCodeStart":1,"sourceCodeEnd":31,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/auth/src/utils.ts#L1-L31","documentation":"getTokenIssuer decodes a JWT and extracts its `iss` claim. This error is thrown when the token decodes to a valid JWT structure but its `payload` component is missing or is not an object — i.e. `decoded.payload` is absent or a non-object value. The library requires a well-formed complete decode ({ complete: true }) with an object payload before it will trust any claim.","triggerScenarios":"Calling getTokenIssuer(accessToken) where jwt.decode(accessToken, { complete: true }) returns { header } with no payload, or payload is a string/number instead of an object — typically a hand-crafted, truncated, or corrupted token whose payload segment is empty or malformed base64.","commonSituations":"Tokens truncated during copy/paste (payload segment cut off), tokens manually assembled for testing, env vars holding stale or corrupted values, or a token that is a JWS with empty payload ('ey...hbGci....e30').","solutions":["Inspect the token at jwt.io or jwt.decode to confirm the payload segment exists and is valid base64 JSON","Regenerate the token from your auth provider — do not hand-edit token strings","Verify the correct token is being passed (access token vs API key vs session id)","Confirm no truncation/corruption in env vars or config files storing the token"],"exampleFix":"// before\nconst issuer = getTokenIssuer(tokenFragment); // token truncated, payload missing\n// after\nconst fullToken = await getAccessTokenFromProvider(); // fetch a complete token\nconst issuer = getTokenIssuer(fullToken);","handlingStrategy":"validation","validationCode":"function hasDecodablePayload(token: string): boolean {\n  const parts = token.split('.');\n  if (parts.length !== 3) return false;\n  try {\n    const payload = JSON.parse(Buffer.from(parts[1], 'base64url').toString('utf8'));\n    return payload !== null && typeof payload === 'object' && !Array.isArray(payload);\n  } catch {\n    return false;\n  }\n}\n// call getTokenIssuer only if hasDecodablePayload(token)","typeGuard":"function hasObjectPayload(decoded: jwt.Jwt | null): decoded is jwt.Jwt & { payload: jwt.JwtPayload } {\n  return decoded !== null && 'payload' in decoded && typeof decoded.payload === 'object' && decoded.payload !== null;\n}","tryCatchPattern":"try {\n  const issuer = getTokenIssuer(token);\n} catch (e) {\n  if (e instanceof Error && e.message === 'Invalid token payload') {\n    // token structurally incomplete: re-fetch/refresh the token\n  }\n  throw e;\n}","preventionTips":["Never hand-edit or truncate JWT strings; always take them from the provider response","Validate token shape (3 dot-separated segments) before passing to auth utilities","Keep tokens out of configs where copy/paste truncation is likely"],"tags":["jwt","auth","token-payload","validation"],"backgroundTag":"jwt-malformed-token","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}