{"record":{"id":"c01bd1d74d850e97","repo":"mastra-ai/mastra","slug":"bright-data-api-token-is-required-pass-apikey","errorCode":null,"errorMessage":"Bright Data API token is required. Pass { apiKey } or set BRIGHTDATA_API_TOKEN env var.","messagePattern":"Bright Data API token is required\\. Pass (.+?) or set BRIGHTDATA_API_TOKEN env var\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"integrations/brightdata/src/client.ts","lineNumber":138,"sourceCode":"    url,\n    zone,\n  };\n\n  if (options.country) {\n    body.country = options.country;\n  }\n\n  if (options.dataFormat && options.dataFormat !== 'html') {\n    body.data_format = options.dataFormat;\n  }\n\n  return body;\n}\n\nexport function getBrightDataClient(config?: BrightDataClientOptions): BrightDataClient {\n  const apiKey = config?.apiKey ?? process.env.BRIGHTDATA_API_TOKEN;\n  if (!apiKey) {\n    throw new Error('Bright Data API token is required. Pass { apiKey } or set BRIGHTDATA_API_TOKEN env var.');\n  }\n\n  const timeout = config?.timeout;\n  const serpZone = config?.serpZone ?? process.env.BRIGHTDATA_SERP_ZONE ?? DEFAULT_SERP_ZONE;\n  const webUnlockerZone =\n    config?.webUnlockerZone ?? process.env.BRIGHTDATA_WEB_UNLOCKER_ZONE ?? DEFAULT_WEB_UNLOCKER_ZONE;\n\n  return {\n    search: {\n      google: async (query: string, options: SearchOptions = {}) => {\n        if (options.language && !/^[a-z]{2}$/i.test(options.language)) {\n          throw new Error('language must be a two-letter code (e.g. \"en\", \"es\")');\n        }\n\n        const normalizedOptions = options.language ? { ...options, language: options.language.toLowerCase() } : options;\n\n        const url = buildGoogleSearchUrl(query, normalizedOptions);\n        return requestBrightData(","sourceCodeStart":120,"sourceCodeEnd":156,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/integrations/brightdata/src/client.ts#L120-L156","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Set BRIGHTDATA_API_TOKEN in the environment (note the exact name: BRIGHTDATA_API_TOKEN, not BRIGHT_DATA_*).","Or pass the key explicitly: getBrightDataClient({ apiKey: '<token>' }).","If using a .env file, ensure dotenv is loaded before getBrightDataClient runs.","In CI/production, confirm the secret is injected into the process environment under the exact variable name."],"exampleFix":"// before\nconst client = getBrightDataClient(); // no env var set\n// after\nconst client = getBrightDataClient({ apiKey: process.env.BRIGHTDATA_API_TOKEN }); // with BRIGHTDATA_API_TOKEN set in .env","handlingStrategy":"validation","validationCode":"function requireBrightDataConfig(): { apiKey: string } {\n  const apiKey = process.env.BRIGHTDATA_API_TOKEN;\n  if (!apiKey) {\n    throw new Error('Set BRIGHTDATA_API_TOKEN before initializing the Bright Data client');\n  }\n  return { apiKey };\n}","typeGuard":"function hasBrightDataConfig(c: unknown): c is { apiKey: string } {\n  return typeof c === 'object' && c !== null && typeof (c as { apiKey?: unknown }).apiKey === 'string' && (c as { apiKey: string }).apiKey.length > 0;\n}","tryCatchPattern":"let client: BrightDataClient;\ntry {\n  client = getBrightDataClient();\n} catch (err) {\n  if (err instanceof Error && err.message.includes('API token is required')) {\n    throw new Error('Startup config error: BRIGHTDATA_API_TOKEN is not set');\n  }\n  throw err;\n}","preventionTips":["Load dotenv at process entry before any client construction.","Fail fast at startup with an env-var presence check for BRIGHTDATA_API_TOKEN.","Use the exact variable name BRIGHTDATA_API_TOKEN in CI/CD secret configuration.","Add a smoke test that constructs the client in every environment."],"tags":["configuration","env-var","missing-config"],"backgroundTag":"missing-env-var","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}