mastra-ai/mastra · error · Error

WorkOS redirect URI is required. Provide it in the options,

Error message

WorkOS redirect URI is required. Provide it in the options, set the WORKOS_REDIRECT_URI environment variable, or call init() with a publicUrl.

What it means

getLoginUrl() builds the WorkOS SSO authorization URL and requires a redirect URI. It uses the redirectUri argument, falling back to the provider's configured redirectUri (from options, WORKOS_REDIRECT_URI, or init(publicUrl)). If neither resolves, it throws because the OAuth flow has no callback address.

Source

Thrown at auth/workos/src/auth-provider.ts:519

        return undefined;
      }
      current = (current as Record<string, unknown>)[segment];
    }

    return typeof current === 'string' ? current : undefined;
  }

  // ============================================================================
  // ISSOProvider Implementation
  // ============================================================================

  /**
   * Get the URL to redirect users to for SSO login.
   */
  getLoginUrl(redirectUri: string, state: string): string {
    const resolvedRedirectUri = redirectUri || this.redirectUri;
    if (!resolvedRedirectUri) {
      throw new Error(
        'WorkOS redirect URI is required. ' +
          'Provide it in the options, set the WORKOS_REDIRECT_URI environment variable, or call init() with a publicUrl.',
      );
    }

    const baseOptions = {
      clientId: this.clientId,
      redirectUri: resolvedRedirectUri,
      state,
    };

    if (this.ssoConfig?.connection) {
      return this.workos.userManagement.getAuthorizationUrl({
        ...baseOptions,
        connectionId: this.ssoConfig.connection,
      });
    } else if (this.ssoConfig?.provider) {
      return this.workos.userManagement.getAuthorizationUrl({

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set the WORKOS_REDIRECT_URI environment variable to your full callback URL
2. Call auth.init({ publicUrl: 'https://your-app.example.com' }) so the callback path can be derived
3. Pass the redirect URI explicitly to getLoginUrl(redirectUri, state)
4. Ensure the redirect URI is registered as an allowed redirect in the WorkOS dashboard

Example fix

// before
const auth = new MastraAuthWorkos({ apiKey, clientId });
const url = auth.getLoginUrl('', state);
// after
const auth = new MastraAuthWorkos({ apiKey, clientId, redirectUri: 'https://app.example.com/auth/callback' });
const url = auth.getLoginUrl();

function assertRedirectUri(opts, hostPublicUrl) {
  const uri = opts?.redirectUri ?? process.env.WORKOS_REDIRECT_URI ??
    (hostPublicUrl ? new URL('/auth/callback', hostPublicUrl).toString() : null);
  if (!uri) throw new Error('WorkOS redirect URI missing: set WORKOS_REDIRECT_URI or configure publicUrl');
  if (!uri.startsWith('https://') && !uri.startsWith('http://localhost')) {
    throw new Error('WorkOS redirect URI must be an absolute URL: ' + uri);
  }
  return uri;
}

function canResolveLoginUrl(opts, hostPublicUrl) {
  return Boolean(opts?.redirectUri || process.env.WORKOS_REDIRECT_URI || hostPublicUrl);
}

try {
  const url = auth.getLoginUrl(redirectUriArg, state);
} catch (e) {
  if (e.message.includes('redirect URI is required')) {
    throw new ConfigError('Set WORKOS_REDIRECT_URI or call auth.init({ publicUrl }) before login');
  }
  throw e;
}

When it happens

Trigger: Calling `auth.getLoginUrl()` (or the internal path that invokes it) with an empty redirectUri argument while the provider was constructed without WORKOS_REDIRECT_URI and init() was never called with a publicUrl.

Common situations: Deployed behind a proxy where publicUrl is not configured; env var name typo (WORKOS_REDIRECTURL); new environment (staging) missing the env var; calling getLoginUrl directly in custom code without passing a redirect URI.

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

• MastraAuthWorkos could not resolve a callback URL: pass `red
• Redirect URI is required for SSO. Set AUTH0_REDIRECT_URI or
• Redirect URI is required for Google SSO. Set GOOGLE_REDIRECT
• State token has expired
• Redirect URI is required for SSO login

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