{"record":{"id":"5295c2f524e41ab0","repo":"mastra-ai/mastra","slug":"neon-auth-base-url-is-required-please-provide-it","errorCode":null,"errorMessage":"Neon Auth base URL is required, please provide it in the options or set the NEON_AUTH_BASE_URL environment variable","messagePattern":"Neon Auth base URL is required, please provide it in the options or set the NEON_AUTH_BASE_URL environment variable","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"auth/neon/src/index.ts","lineNumber":175,"sourceCode":" *\n * @see https://neon.com/docs/auth/overview\n */\nexport class MastraAuthNeon\n  extends MastraAuthProvider<NeonAuthUser>\n  implements IUserProvider<EEUser>, ICredentialsProvider<EEUser>, ISessionProvider<Session>\n{\n  protected baseUrl: string;\n  protected jwksUrl: string;\n  public sessionCookieName: string;\n  protected signUpEnabledConfig: boolean;\n\n  constructor(options?: MastraAuthNeonOptions) {\n    super({ name: options?.name ?? 'neon' });\n\n    const baseUrl = options?.baseUrl ?? process.env.NEON_AUTH_BASE_URL;\n\n    if (!baseUrl) {\n      throw new Error(\n        'Neon Auth base URL is required, please provide it in the options or set the NEON_AUTH_BASE_URL environment variable',\n      );\n    }\n\n    this.baseUrl = stripTrailingSlashes(baseUrl);\n    this.jwksUrl = options?.jwksUrl ?? process.env.NEON_AUTH_JWKS_URL ?? `${this.baseUrl}/auth/jwks`;\n    this.sessionCookieName = options?.sessionCookieName ?? 'neonauth.session_token';\n    this.signUpEnabledConfig = options?.signUpEnabled ?? true;\n\n    this.registerOptions(options);\n  }\n\n  /** Expose the base URL for RBAC or other consumers. */\n  getBaseUrl(): string {\n    return this.baseUrl;\n  }\n\n  isSignUpEnabled(): boolean {","sourceCodeStart":157,"sourceCodeEnd":193,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/auth/neon/src/index.ts#L157-L193","documentation":"The MastraAuthNeon constructor requires a base URL for the Neon Auth instance, supplied either via options.baseUrl or the NEON_AUTH_BASE_URL environment variable. If neither is present the provider cannot construct JWKS/auth endpoints, so it fails fast at construction time rather than producing broken requests later.","triggerScenarios":"Calling new MastraAuthNeon() (or with an options object lacking baseUrl) in a process where process.env.NEON_AUTH_BASE_URL is undefined.","commonSituations":"Forgetting to add the env var to .env or the deployment platform's secret settings; misspelling the variable name (e.g. NEON_BASE_URL); env vars not loaded because dotenv is initialized after the provider is constructed.","solutions":["Pass baseUrl explicitly: new MastraAuthNeon({ baseUrl: 'https://your-neon-auth-endpoint' })","Set NEON_AUTH_BASE_URL in your environment/.env before the constructor runs","Verify the env var name is spelled exactly NEON_AUTH_BASE_URL and is loaded (import dotenv/config before construction)","Copy the correct Neon Auth base URL from your Neon project dashboard"],"exampleFix":"// before\nconst auth = new MastraAuthNeon();\n// after\nconst auth = new MastraAuthNeon({ baseUrl: process.env.NEON_AUTH_BASE_URL ?? 'https://ep-xxx.neon-auth.app' });","handlingStrategy":"validation","validationCode":"function createNeonAuth(options?: MastraAuthNeonOptions) {\n  const baseUrl = options?.baseUrl ?? process.env.NEON_AUTH_BASE_URL;\n  if (!baseUrl) {\n    throw new Error('Set NEON_AUTH_BASE_URL or pass baseUrl to MastraAuthNeon');\n  }\n  return new MastraAuthNeon({ ...options, baseUrl });\n}","typeGuard":"function hasNeonBaseUrl(options?: MastraAuthNeonOptions): options is MastraAuthNeonOptions & { baseUrl: string } {\n  return typeof options?.baseUrl === 'string' && options.baseUrl.length > 0;\n}","tryCatchPattern":"let auth: MastraAuthNeon;\ntry {\n  auth = new MastraAuthNeon();\n} catch (err) {\n  if (err instanceof Error && err.message.includes('base URL is required')) {\n    console.error('Missing NEON_AUTH_BASE_URL; check .env and dotenv load order');\n  }\n  throw err;\n}","preventionTips":["Set NEON_AUTH_BASE_URL in .env and every deployment environment's config","Import 'dotenv/config' (or equivalent) before constructing auth providers","Fail fast at startup with an env validation library (zod + env schema)","Watch for typos: the exact variable name is NEON_AUTH_BASE_URL"],"tags":["auth","neon","configuration","env"],"backgroundTag":"missing-env-var","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}