mastra-ai/mastra · error

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

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.

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)

Solutions

1. Pass baseUrl explicitly: new MastraAuthNeon({ baseUrl: 'https://your-neon-auth-endpoint' })
2. Set NEON_AUTH_BASE_URL in your environment/.env before the constructor runs
3. Verify the env var name is spelled exactly NEON_AUTH_BASE_URL and is loaded (import dotenv/config before construction)
4. 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' });

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 });
}

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

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;
}

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

• Google service account private key signing failed (${(err as
• Clerk JWKS URI, secret key and publishable key are required,
• Cookie password must be at least 32 characters for SSO. Set
• Redirect URI is required for SSO login
• Invalid email or password

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