mastra-ai/mastra · critical

Auth0 domain and audience are required, please provide them

Error message

Auth0 domain and audience are required, please provide them in the options or set the environment variables AUTH0_DOMAIN and AUTH0_AUDIENCE

What it means

The AuthOServerAuth (auth0) provider constructor requires an Auth0 domain and audience, either passed via the options object or resolved from the AUTH0_DOMAIN and AUTH0_AUDIENCE environment variables. If neither source yields a truthy value, the constructor throws immediately at provider instantiation time so the misconfiguration fails fast instead of producing broken OAuth URLs later.

Source

Thrown at auth/auth0/src/index.ts:300

  // SSO fields
  private clientId: string | null;
  private clientSecret: string | null;
  private _redirectUri: string | null;
  private scopes: string[];
  private cookieName: string;
  private cookieMaxAge: number;
  private cookiePassword: string;
  private secureCookies: boolean;
  private ssoEnabled: boolean;

  constructor(options?: MastraAuthAuth0Options) {
    super({ name: options?.name ?? 'auth0' });

    const domain = options?.domain ?? process.env.AUTH0_DOMAIN;
    const audience = options?.audience ?? process.env.AUTH0_AUDIENCE;

    if (!domain || !audience) {
      throw new Error(
        'Auth0 domain and audience are required, please provide them in the options or set the environment variables AUTH0_DOMAIN and AUTH0_AUDIENCE',
      );
    }

    this.domain = domain;
    this.audience = audience;

    // SSO configuration (optional — enables Studio login)
    const clientId = options?.clientId ?? process.env.AUTH0_CLIENT_ID;
    const clientSecret = options?.clientSecret ?? process.env.AUTH0_CLIENT_SECRET;
    const redirectUri = options?.redirectUri ?? process.env.AUTH0_REDIRECT_URI;
    const cookiePassword =
      options?.session?.cookiePassword ??
      process.env.AUTH0_COOKIE_PASSWORD ??
      crypto.randomUUID() + crypto.randomUUID();

    this.clientId = clientId ?? null;
    this.clientSecret = clientSecret ?? null;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set both environment variables AUTH0_DOMAIN (e.g. dev-xyz.us.auth0.com) and AUTH0_AUDIENCE (your Auth0 API identifier) in the deployment environment
2. Pass them explicitly in options: new AuthOServerAuth({ domain: '...', audience: '...' })
3. Verify your .env file is actually loaded by the runtime (dotenv import, framework env loading) and included in the deployment artifact
4. Check for typos in variable names and that secrets are not scoped out in CI/CD

Example fix

// before
new AuthOServerAuth({ name: 'auth0' });
// after
new AuthOServerAuth({
  name: 'auth0',
  domain: 'dev-xyz.us.auth0.com',
  audience: 'https://my-api.example.com',
});

function assertAuth0Config(opts) {
  const domain = opts?.domain ?? process.env.AUTH0_DOMAIN;
  const audience = opts?.audience ?? process.env.AUTH0_AUDIENCE;
  if (!domain) throw new Error('AUTH0_DOMAIN (or options.domain) must be set');
  if (!audience) throw new Error('AUTH0_AUDIENCE (or options.audience) must be set');
  return { domain, audience };
}
// call before constructing the provider
assertAuth0Config(options);

function hasAuth0Env(env: NodeJS.ProcessEnv): env is NodeJS.ProcessEnv &
  { AUTH0_DOMAIN: string; AUTH0_AUDIENCE: string } {
  return Boolean(env.AUTH0_DOMAIN && env.AUTH0_AUDIENCE);
}

let provider;
try {
  provider = new AuthOServerAuth(options);
} catch (e) {
  if (e instanceof Error && e.message.includes('Auth0 domain and audience are required')) {
    throw new Error('Auth0 provider misconfigured: set AUTH0_DOMAIN and AUTH0_AUDIENCE', { cause: e });
  }
  throw e;
}

When it happens

Trigger: Calling `new AuthOServerAuth()` (or the factory with auth0 provider config) with neither `options.domain`/`options.audience` set nor AUTH0_DOMAIN/AUTH0_AUDIENCE exported in the environment running the server.

Common situations: Deploying to a platform where .env files are not loaded (serverless, Docker without env_file); forgetting to set the env vars in CI/CD or production; passing only domain but not audience (or vice versa) in options; typos in env var names.

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

• Cookie password must be at least 32 characters for SSO. Set
• Redirect URI is required for SSO. Set AUTH0_REDIRECT_URI or
• Bright Data API token is required. Pass { apiKey } or set BR
• @mastra/livekit: set LIVEKIT_URL or pass serverUrl to dispat
• ${name} must be an integer ${range}; received ${JSON.stringi

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