mastra-ai/mastra · error · 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

MastraAuthOkta's RBAC provider requires an Okta domain to construct its Okta API client. The constructor resolves the domain from options.domain first, then the OKTA_DOMAIN environment variable. If neither is set, it throws immediately at construction time so misconfiguration fails fast rather than at first request.

Source

Thrown at auth/okta/src/rbac-provider.ts:95

   * Expose roleMapping for middleware access.
   * This allows the authorization middleware to resolve permissions
   * without needing to call the async methods.
   */
  get roleMapping(): RoleMapping {
    return this.options.roleMapping;
  }

  /**
   * Create a new Okta RBAC provider.
   *
   * @param options - RBAC configuration options
   */
  constructor(options: MastraRBACOktaOptions) {
    const domain = options.domain ?? process.env.OKTA_DOMAIN;
    const apiToken = options.apiToken ?? process.env.OKTA_API_TOKEN;

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

    if (!apiToken) {
      throw new Error(
        'Okta API token is required for RBAC. ' +
          'Provide it in the options or set OKTA_API_TOKEN environment variable.',
      );
    }

    this.oktaClient = new Client({
      orgUrl: `https://${domain}`,
      token: apiToken,
    });

    this.options = options;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set the OKTA_DOMAIN environment variable (e.g. dev-12345678.okta.com)
2. Pass domain explicitly: new MastraRBACOkta({ domain: 'dev-12345678.okta.com', apiToken })
3. Verify your .env file is actually loaded (dotenv/config, platform env settings) before construction
4. Ensure the env var name is exactly OKTA_DOMAIN (case-sensitive)

Example fix

// before
const rbac = new MastraRBACOkta({ apiToken: token });
// after
const rbac = new MastraRBACOkta({ domain: process.env.OKTA_DOMAIN, apiToken: token });

function assertOktaConfig(opts) {
  const domain = opts?.domain ?? process.env.OKTA_DOMAIN;
  if (!domain) throw new Error('OKTA domain missing: set OKTA_DOMAIN or pass options.domain');
  if (!/^https?:\/\/.+|^.+\.okta\.com\/?$/.test(domain)) throw new Error('OKTA domain looks invalid: ' + domain);
  return domain;
}

function hasOktaDomain(o) {
  return typeof o === 'object' && o !== null && typeof o.domain === 'string' && o.domain.length > 0;
}

let rbac;
try {
  rbac = new MastraRBACOkta(options);
} catch (e) {
  if (e.message.includes('OKTA_DOMAIN')) {
    throw new ConfigError('Okta RBAC misconfigured: set OKTA_DOMAIN or pass { domain }');
  }
  throw e;
}

When it happens

Trigger: Calling `new MastraRBACOkta(options)` where options.domain is undefined and process.env.OKTA_DOMAIN is unset or empty.

Common situations: Forgetting to load a .env file before instantiating; deploying to an environment where OKTA_DOMAIN was never set; passing the wrong option key name (e.g. {oktaDomain}) so options.domain is undefined.

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 API token is required for RBAC. Provide it in the optio
• Okta domain is required. Provide it in the options or set OK
• Okta client ID is required. Provide it in the options or set
• Supabase URL and anon key are required, please provide them
• WorkOS API key and client ID are required. Provide them in t

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