Neon Auth base URL is required, please provide it in the…

Error message

Neon Auth base URL is required, please provide it in the options or set the NEON_AUTH_BASE_URL environment variable

What it means

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.

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

Example fix

// before
const auth = new MastraAuthNeon();
// after
const auth = new MastraAuthNeon({ baseUrl: process.env.NEON_AUTH_BASE_URL ?? 'https://ep-xxx.neon-auth.app' });

Defensive patterns

Strategy: validation

Validate before calling

function createNeonAuth(options?: MastraAuthNeonOptions) {
  const baseUrl = options?.baseUrl ?? process.env.NEON_AUTH_BASE_URL;
  if (!baseUrl) {
    throw new Error('Set NEON_AUTH_BASE_URL or pass baseUrl to MastraAuthNeon');
  }
  return new MastraAuthNeon({ ...options, baseUrl });
}

Type guard

function hasNeonBaseUrl(options?: MastraAuthNeonOptions): options is MastraAuthNeonOptions & { baseUrl: string } {
  return typeof options?.baseUrl === 'string' && options.baseUrl.length > 0;
}

Try / catch

let auth: MastraAuthNeon;
try {
  auth = new MastraAuthNeon();
} catch (err) {
  if (err instanceof Error && err.message.includes('base URL is required')) {
    console.error('Missing NEON_AUTH_BASE_URL; check .env and dotenv load order');
  }
  throw err;
}

Prevention

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

When it happens

Trigger: Calling new MastraAuthNeon() (or with an options object lacking baseUrl) in a process where process.env.NEON_AUTH_BASE_URL is undefined.

Common situations: 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.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

AI-assisted analysis of mastra-ai/mastra@75dd419e61 (2026-08-30). Data as JSON: /api/errors/5295c2f524e41ab0. Report an issue: GitHub.

Appendix: source

Thrown at auth/neon/src/index.ts:175

 *
 * @see https://neon.com/docs/auth/overview
 */
export class MastraAuthNeon
  extends MastraAuthProvider<NeonAuthUser>
  implements IUserProvider<EEUser>, ICredentialsProvider<EEUser>, ISessionProvider<Session>
{
  protected baseUrl: string;
  protected jwksUrl: string;
  public sessionCookieName: string;
  protected signUpEnabledConfig: boolean;

  constructor(options?: MastraAuthNeonOptions) {
    super({ name: options?.name ?? 'neon' });

    const baseUrl = options?.baseUrl ?? process.env.NEON_AUTH_BASE_URL;

    if (!baseUrl) {
      throw new Error(
        'Neon Auth base URL is required, please provide it in the options or set the NEON_AUTH_BASE_URL environment variable',
      );
    }

    this.baseUrl = stripTrailingSlashes(baseUrl);
    this.jwksUrl = options?.jwksUrl ?? process.env.NEON_AUTH_JWKS_URL ?? `${this.baseUrl}/auth/jwks`;
    this.sessionCookieName = options?.sessionCookieName ?? 'neonauth.session_token';
    this.signUpEnabledConfig = options?.signUpEnabled ?? true;

    this.registerOptions(options);
  }

  /** Expose the base URL for RBAC or other consumers. */
  getBaseUrl(): string {
    return this.baseUrl;
  }

  isSignUpEnabled(): boolean {

View on GitHub (pinned to 75dd419e61)