{"record":{"id":"6570eaabc9bf70cd","repo":"mastra-ai/mastra","slug":"jwt-auth-secret-is-required","errorCode":null,"errorMessage":"JWT auth secret is required","messagePattern":"JWT auth secret is required","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"critical","filePath":"packages/auth/src/jwt.ts","lineNumber":41,"sourceCode":"  return {\n    id,\n    email: str(payload.email),\n    name: str(payload.name),\n    avatarUrl: str(payload.avatarUrl) || str(payload.avatar_url) || str(payload.picture),\n  };\n}\n\nexport class MastraJwtAuth extends MastraAuthProvider<JwtUser> implements IUserProvider {\n  protected secret: string;\n  private mapUser: (payload: JwtUser) => User | null;\n\n  constructor(options?: MastraJwtAuthOptions) {\n    super({ name: options?.name ?? 'jwt' });\n\n    this.secret = options?.secret ?? process.env.JWT_AUTH_SECRET ?? '';\n\n    if (!this.secret) {\n      throw new Error('JWT auth secret is required');\n    }\n\n    this.mapUser = options?.mapUser ?? defaultMapUser;\n    this.registerOptions(options);\n  }\n\n  async authenticateToken(token: string): Promise<JwtUser> {\n    return jwt.verify(token, this.secret) as JwtUser;\n  }\n\n  async authorizeUser(user: JwtUser) {\n    return !!user;\n  }\n\n  async getCurrentUser(request: Request): Promise<User | null> {\n    const authHeader = request.headers.get('authorization');\n    const token = authHeader?.toLowerCase().startsWith('bearer ') ? authHeader.slice(7).trim() : null;\n    if (!token) return null;","sourceCodeStart":23,"sourceCodeEnd":59,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/auth/src/jwt.ts#L23-L59","documentation":"MastraJwtAuth's constructor resolves its signing/verification secret from options.secret, falling back to the JWT_AUTH_SECRET environment variable, and defaults to an empty string. If no non-empty secret is found it immediately throws 'JWT auth secret is required', because a JWT auth provider is unusable and unsafe without a secret.","triggerScenarios":"new MastraJwtAuth() with no options.secret while process.env.JWT_AUTH_SECRET is unset or empty string; also occurs if the env var is loaded after construction (e.g. dotenv initialized too late) or not loaded in the deployment environment at all.","commonSituations":"Forgetting JWT_AUTH_SECRET in .env, env vars not propagated to the deployed service (Docker/Cloud runtimes, CI), dotenv not called before server construction, or a typo'd variable name.","solutions":["Set the JWT_AUTH_SECRET environment variable (e.g. in .env or the deployment's secret/config settings)","Or pass the secret explicitly: new MastraJwtAuth({ secret: '<your-secret>' })","Ensure dotenv/config loading runs before the MastraJwtAuth constructor executes","Generate a strong secret if missing, e.g. `openssl rand -base64 32`"],"exampleFix":"// before\nconst auth = new MastraJwtAuth();\n// after\nconst auth = new MastraJwtAuth({ secret: process.env.JWT_AUTH_SECRET }); // with JWT_AUTH_SECRET set in env","handlingStrategy":"validation","validationCode":"const secret = options?.secret ?? process.env.JWT_AUTH_SECRET;\nif (!secret) {\n  throw new Error('JWT_AUTH_SECRET is not set. Generate one with: openssl rand -base64 32');\n}\nconst auth = new MastraJwtAuth({ secret });","typeGuard":"export function hasJwtSecret(opts?: { secret?: string }): opts is { secret: string } & NonNullable<Parameters<typeof MastraJwtAuth>[0]> {\n  return typeof opts?.secret === 'string' && opts.secret.length > 0 || !!process.env.JWT_AUTH_SECRET;\n}","tryCatchPattern":"let auth;\ntry {\n  auth = new MastraJwtAuth({ secret: process.env.JWT_AUTH_SECRET });\n} catch (e) {\n  if (e instanceof Error && e.message === 'JWT auth secret is required') {\n    console.error('Set JWT_AUTH_SECRET in your environment before booting the server');\n    process.exit(1);\n  }\n  throw e;\n}","preventionTips":["Always set JWT_AUTH_SECRET in .env and in every deployment's secret manager","Load dotenv/config before constructing auth providers","Fail fast at boot: construct MastraJwtAuth during startup, not lazily per request","Generate strong secrets (openssl rand -base64 32) and never commit them"],"tags":["jwt","auth","config","env"],"backgroundTag":"missing-env-var","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}