mastra-ai/mastra · error

Google client ID is required. Provide it in the options or s

Error message

Google client ID is required. Provide it in the options or set GOOGLE_CLIENT_ID environment variable.

What it means

The MastraAuthGoogle constructor requires a Google OAuth client ID. It reads options.clientId first, then falls back to the GOOGLE_CLIENT_ID environment variable. If neither is set it cannot initialize the provider, so it throws immediately at construction time rather than failing later mid-request.

Source

Thrown at auth/google/src/auth-provider.ts:239

  protected clientId: string;
  private clientSecret: string | null;
  private redirectUri: string | null;
  private scopes: string[];
  private cookieName: string;
  private cookieMaxAge: number;
  private cookiePassword: string;
  private secureCookies: boolean;
  private allowedDomains: string[];
  private hostedDomain?: string;
  private ssoEnabled: boolean;
  private jwks: ReturnType<typeof createRemoteJWKSet>;

  constructor(options?: MastraAuthGoogleOptions) {
    super({ name: options?.name ?? 'google' });

    const clientId = options?.clientId ?? process.env.GOOGLE_CLIENT_ID;
    if (!clientId) {
      throw new Error(
        'Google client ID is required. Provide it in the options or set GOOGLE_CLIENT_ID environment variable.',
      );
    }

    const allowedDomains = normalizeAllowedDomains(options?.allowedDomains ?? process.env.GOOGLE_ALLOWED_DOMAINS);
    const configuredHostedDomain = normalizeDomain(options?.hostedDomain ?? process.env.GOOGLE_HOSTED_DOMAIN);
    const clientSecret = options?.clientSecret ?? process.env.GOOGLE_CLIENT_SECRET;
    const redirectUri = options?.redirectUri ?? process.env.GOOGLE_REDIRECT_URI;
    const hasConfiguredCookiePassword = !!(options?.session?.cookiePassword ?? process.env.GOOGLE_COOKIE_PASSWORD);
    const cookiePassword =
      options?.session?.cookiePassword ??
      process.env.GOOGLE_COOKIE_PASSWORD ??
      crypto.randomUUID() + crypto.randomUUID();

    this.clientId = clientId;
    this.clientSecret = clientSecret ?? null;
    this.redirectUri = redirectUri ?? null;
    this.scopes = options?.scopes ?? DEFAULT_SCOPES;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set the GOOGLE_CLIENT_ID environment variable in the environment where the server runs.
2. Or pass clientId explicitly: new MastraAuthGoogle({ clientId: 'xxx.apps.googleusercontent.com' }).
3. Ensure dotenv/config is loaded before the provider module is imported/instantiated.
4. Confirm the value in your OAuth/OIDC console matches (Google Cloud Console > Credentials > OAuth 2.0 Client ID).

Example fix

// before
const auth = new MastraAuthGoogle({});

// after
const auth = new MastraAuthGoogle({
  clientId: process.env.GOOGLE_CLIENT_ID,
});

if (!options?.clientId && !process.env.GOOGLE_CLIENT_ID) {
  throw new Error('Set GOOGLE_CLIENT_ID before constructing MastraAuthGoogle');
}
const auth = new MastraAuthGoogle(options);

function hasGoogleClientId(o?: { clientId?: string }): o is { clientId: string } & typeof o {
  return typeof o?.clientId === 'string' && o.clientId.length > 0;
}

try {
  const auth = new MastraAuthGoogle(options);
} catch (err) {
  if (err instanceof Error && err.message.includes('client ID is required')) {
    console.error('Missing GOOGLE_CLIENT_ID — check env config for this environment');
    process.exit(1);
  }
  throw err;
}

When it happens

Trigger: new MastraAuthGoogle() or new MastraAuthGoogle({ name: 'google' }) with no clientId in the options object while process.env.GOOGLE_CLIENT_ID is undefined (not set, or set only after the process started / in a different environment).

Common situations: Deploying to production/cloud where the .env file isn't copied; forgetting to configure GOOGLE_CLIENT_ID in the hosting platform's env settings; loading dotenv after the provider is instantiated; a typo like GOOGLE_CLIENTID.

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

• LinearIntegration is missing required config: ${missing.join
• Redirect URI is required for Google SSO. Set GOOGLE_REDIRECT
• [mastra/auth-ee] ${featureList} ${configuredFeatures.length
• Clerk JWKS URI, secret key and publishable key are required,
• Redirect URI is required for SSO login

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