mastra-ai/mastra · error

Bright Data API token is required. Pass { apiKey } or set BR

Error message

Bright Data API token is required. Pass { apiKey } or set BRIGHTDATA_API_TOKEN env var.

What it means

getBrightDataClient requires an API key from either the config argument or the BRIGHTDATA_API_TOKEN environment variable. When neither is present it throws this error before constructing the client. This is a fail-fast configuration check so callers never build a client that cannot authenticate.

Source

Thrown at integrations/brightdata/src/client.ts:138

    url,
    zone,
  };

  if (options.country) {
    body.country = options.country;
  }

  if (options.dataFormat && options.dataFormat !== 'html') {
    body.data_format = options.dataFormat;
  }

  return body;
}

export function getBrightDataClient(config?: BrightDataClientOptions): BrightDataClient {
  const apiKey = config?.apiKey ?? process.env.BRIGHTDATA_API_TOKEN;
  if (!apiKey) {
    throw new Error('Bright Data API token is required. Pass { apiKey } or set BRIGHTDATA_API_TOKEN env var.');
  }

  const timeout = config?.timeout;
  const serpZone = config?.serpZone ?? process.env.BRIGHTDATA_SERP_ZONE ?? DEFAULT_SERP_ZONE;
  const webUnlockerZone =
    config?.webUnlockerZone ?? process.env.BRIGHTDATA_WEB_UNLOCKER_ZONE ?? DEFAULT_WEB_UNLOCKER_ZONE;

  return {
    search: {
      google: async (query: string, options: SearchOptions = {}) => {
        if (options.language && !/^[a-z]{2}$/i.test(options.language)) {
          throw new Error('language must be a two-letter code (e.g. "en", "es")');
        }

        const normalizedOptions = options.language ? { ...options, language: options.language.toLowerCase() } : options;

        const url = buildGoogleSearchUrl(query, normalizedOptions);
        return requestBrightData(

View on GitHub (pinned to 75dd419e61)

Solutions

1. Set BRIGHTDATA_API_TOKEN in the environment (note the exact name: BRIGHTDATA_API_TOKEN, not BRIGHT_DATA_*).
2. Or pass the key explicitly: getBrightDataClient({ apiKey: '<token>' }).
3. If using a .env file, ensure dotenv is loaded before getBrightDataClient runs.
4. In CI/production, confirm the secret is injected into the process environment under the exact variable name.

Example fix

// before
const client = getBrightDataClient(); // no env var set
// after
const client = getBrightDataClient({ apiKey: process.env.BRIGHTDATA_API_TOKEN }); // with BRIGHTDATA_API_TOKEN set in .env

function requireBrightDataConfig(): { apiKey: string } {
  const apiKey = process.env.BRIGHTDATA_API_TOKEN;
  if (!apiKey) {
    throw new Error('Set BRIGHTDATA_API_TOKEN before initializing the Bright Data client');
  }
  return { apiKey };
}

function hasBrightDataConfig(c: unknown): c is { apiKey: string } {
  return typeof c === 'object' && c !== null && typeof (c as { apiKey?: unknown }).apiKey === 'string' && (c as { apiKey: string }).apiKey.length > 0;
}

let client: BrightDataClient;
try {
  client = getBrightDataClient();
} catch (err) {
  if (err instanceof Error && err.message.includes('API token is required')) {
    throw new Error('Startup config error: BRIGHTDATA_API_TOKEN is not set');
  }
  throw err;
}

When it happens

Trigger: Calling getBrightDataClient() with no config, with config lacking apiKey, in an environment where process.env.BRIGHTDATA_API_TOKEN is unset or empty — e.g. local dev without .env loaded, CI secrets not injected, or prod env vars missing.

Common situations: Forgetting to add BRIGHTDATA_API_TOKEN to .env / dotenv not loaded; secret named differently in CI (e.g. BRIGHT_DATA_API_KEY); deploying to a new environment without copying secrets; passing config key under the wrong property name.

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

• @mastra/livekit: set LIVEKIT_URL or pass serverUrl to dispat
• Auth0 domain and audience are required, please provide them
• Clerk JWKS URI, secret key and publishable key are required,
• Google client ID is required. Provide it in the options or s
• [MastraAuthGoogle] GOOGLE_COOKIE_PASSWORD is required for Go

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