mastra-ai/mastra · error

Okta domain is required. Provide it in the options or set OK

Error message

Okta domain is required. Provide it in the options or set OKTA_DOMAIN environment variable.

What it means

Validation thrown in the OktaAuthProvider constructor when no Okta domain was provided via options.domain or the OKTA_DOMAIN environment variable. The domain is required to build issuer/token/authorize endpoints, so the provider cannot be constructed without it.

Source

Thrown at auth/okta/src/auth-provider.ts:153

  protected cookieMaxAge: number;
  protected cookiePassword: string;
  protected secureCookies: boolean;
  protected apiToken?: string;
  private jwks: ReturnType<typeof createRemoteJWKSet>;

  constructor(options?: MastraAuthOktaOptions) {
    super({ name: options?.name ?? 'okta' });

    const domain = options?.domain ?? process.env.OKTA_DOMAIN;
    const clientId = options?.clientId ?? process.env.OKTA_CLIENT_ID;
    const clientSecret = options?.clientSecret ?? process.env.OKTA_CLIENT_SECRET;
    const issuer = options?.issuer ?? process.env.OKTA_ISSUER;
    const redirectUri = options?.redirectUri ?? process.env.OKTA_REDIRECT_URI;
    const cookiePassword =
      options?.session?.cookiePassword ?? process.env.OKTA_COOKIE_PASSWORD ?? crypto.randomUUID() + crypto.randomUUID();

    if (!domain) {
      throw new Error('Okta domain is required. Provide it in the options or set OKTA_DOMAIN environment variable.');
    }

    if (!clientId) {
      throw new Error(
        'Okta client ID is required. Provide it in the options or set OKTA_CLIENT_ID environment variable.',
      );
    }

    if (!clientSecret) {
      throw new Error(
        'Okta client secret is required for SSO. Provide it in the options or set OKTA_CLIENT_SECRET environment variable.',
      );
    }

    if (!redirectUri) {
      throw new Error(
        'Okta redirect URI is required for SSO. Provide it in the options or set OKTA_REDIRECT_URI environment variable.',
      );

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set the OKTA_DOMAIN environment variable (e.g. https://dev-123456.okta.com).
2. Pass `domain` explicitly in the provider options object.
3. Verify the .env file is loaded (dotenv/platform config) in the runtime environment.
4. Check for typos in the env var name in both code and deployment config.

Example fix

// before
const auth = new OktaAuthProvider({ clientId: 'abc', clientSecret: 'xyz' });
// after
const auth = new OktaAuthProvider({
  domain: process.env.OKTA_DOMAIN, // set OKTA_DOMAIN=https://dev-123456.okta.com
  clientId: 'abc',
  clientSecret: 'xyz',
});

if (!process.env.OKTA_DOMAIN) {
  throw new Error('Set OKTA_DOMAIN before constructing OktaAuthProvider');
}
const auth = new OktaAuthProvider();

try {
  auth = new OktaAuthProvider();
} catch (e) {
  if (e instanceof Error && e.message.includes('Okta domain is required')) {
    throw new Error('Server misconfiguration: OKTA_DOMAIN missing');
  }
  throw e;
}

When it happens

Trigger: Instantiating the Okta auth provider (new OktaAuthProvider(...)) with options lacking `domain` while OKTA_DOMAIN is unset in the process environment.

Common situations: See trigger scenarios.

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

• Okta client ID is required. Provide it in the options or set
• Okta client secret is required for SSO. Provide it in the op
• Okta redirect URI is required for SSO. Provide it in the opt
• Okta domain is required. Provide it in the options or set OK
• Okta API token is required for RBAC. Provide it in the optio

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