mastra-ai/mastra · error

Okta client ID is required. Provide it in the options or set

Error message

Okta client ID is required. Provide it in the options or set OKTA_CLIENT_ID environment variable.

What it means

Validation thrown in the OktaAuthProvider constructor when no client ID was supplied via options or OKTA_CLIENT_ID environment variable. The client ID identifies the OIDC application to Okta and is mandatory for any auth flow.

Source

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

  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.',
      );
    }

    if (cookiePassword.length < 32) {
      throw new Error('Cookie password must be at least 32 characters. Set OKTA_COOKIE_PASSWORD environment variable.');

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set the OKTA_CLIENT_ID environment variable from the Okta application settings.
2. Pass `clientId` explicitly in the constructor options.
3. Confirm the app integration still exists in the Okta admin console and copy its client ID.
4. Verify the deployment/CI injects the variable into the runtime environment.

Example fix

// before
new OktaAuthProvider({ domain: 'https://dev-123.okta.com' });
// after
new OktaAuthProvider({
  domain: 'https://dev-123.okta.com',
  clientId: process.env.OKTA_CLIENT_ID, // set in env
  clientSecret: process.env.OKTA_CLIENT_SECRET,
});

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

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

When it happens

Trigger: new OktaAuthProvider(...) with domain set but neither options.clientId nor OKTA_CLIENT_ID defined.

Common situations: Env var missing in production after being present locally; OIDC app deleted or ID rotated in the Okta dashboard; secrets manager not injected into the container.

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 domain is required. Provide it in the options or set OK
• 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/a84cbd0734614056. Report an issue: GitHub.