{"record":{"id":"b18694c20997d88a","repo":"mastra-ai/mastra","slug":"firecrawlbrowser-requires-apikey-or-firecrawl-ap","errorCode":null,"errorMessage":"FirecrawlBrowser requires `apiKey` or FIRECRAWL_API_KEY","messagePattern":"FirecrawlBrowser requires `apiKey` or FIRECRAWL_API_KEY","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"browser/firecrawl/src/firecrawl-browser.ts","lineNumber":38,"sourceCode":"/**\n * Mastra browser provider backed by [Firecrawl Browser Sandbox](https://docs.firecrawl.dev/features/browser):\n * provisions remote sessions via API and drives them with the same deterministic tools as {@link AgentBrowser}.\n */\nexport class FirecrawlBrowser extends AgentBrowser {\n  override readonly name = 'FirecrawlBrowser';\n  override readonly provider = 'firecrawl/browser-sandbox';\n\n  /** Narrowed from base `MastraBrowser` (`unknown`) — same pattern as {@link AgentBrowser}. */\n  declare protected sharedManager: BrowserManager | null;\n\n  private readonly firecrawl: Firecrawl;\n  private readonly sessionOpts: FirecrawlBrowserSessionOptions;\n  private sharedFirecrawlSessionId?: string;\n\n  constructor(config: FirecrawlBrowserConfig) {\n    const apiKey = config.apiKey ?? process.env.FIRECRAWL_API_KEY;\n    if (!apiKey) {\n      throw new Error('FirecrawlBrowser requires `apiKey` or FIRECRAWL_API_KEY');\n    }\n    const fc = new Firecrawl({ apiKey, apiUrl: config.apiUrl });\n    const sessionOpts = pickSessionOpts(config);\n\n    super({\n      ...toBaseConfig(config),\n      createThreadManager: opts =>\n        new FirecrawlAgentBrowserThreadManager({\n          ...opts,\n          firecrawl: fc,\n          resolveWebSocketUrl: url => resolveCdpWebSocketUrl(url, opts.logger),\n          sessionOptions: sessionOpts,\n        }),\n    });\n    this.firecrawl = fc;\n    this.sessionOpts = sessionOpts;\n  }\n","sourceCodeStart":20,"sourceCodeEnd":56,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/browser/firecrawl/src/firecrawl-browser.ts#L20-L56","documentation":"FirecrawlBrowser validates configuration at construction time: an API key must come either from the explicit `apiKey` config property or from the FIRECRAWL_API_KEY environment variable. The library throws immediately in the constructor rather than later at request time, so a missing key fails fast. This guards against constructing a browser that cannot authenticate any Firecrawl calls.","triggerScenarios":"Constructing FirecrawlBrowser with a config object lacking `apiKey` while the FIRECRAWL_API_KEY environment variable is unset (or set to an empty string, which is falsy).","commonSituations":"Deploying to an environment where the env var was never set (CI, serverless, Docker without env passthrough); passing an empty-string apiKey; loading .env only in dev but not production; forgetting the config spread when wiring the browser into an agent.","solutions":["Set the FIRECRAWL_API_KEY environment variable to a valid Firecrawl API key","Pass apiKey explicitly in the FirecrawlBrowser config object","Verify the env var is loaded (dotenv/config, Docker -e, CI secrets) before constructing","Check that the value is non-empty and from the correct Firecrawl account"],"exampleFix":"// before\nconst browser = new FirecrawlBrowser({});\n// after\nconst browser = new FirecrawlBrowser({ apiKey: process.env.FIRECRAWL_API_KEY });","handlingStrategy":"validation","validationCode":"const apiKey = config.apiKey ?? process.env.FIRECRAWL_API_KEY;\nif (!apiKey) throw new Error('Set FIRECRAWL_API_KEY or pass apiKey to FirecrawlBrowser');","typeGuard":"function hasFirecrawlKey(config: { apiKey?: string }): config is { apiKey: string } {\n  return Boolean(config.apiKey ?? process.env.FIRECRAWL_API_KEY);\n}","tryCatchPattern":"try {\n  const browser = new FirecrawlBrowser(config);\n} catch (e) {\n  if (e instanceof Error && e.message.includes('apiKey')) {\n    throw new Error('Firecrawl configuration error: missing apiKey / FIRECRAWL_API_KEY');\n  }\n  throw e;\n}","preventionTips":["Validate FIRECRAWL_API_KEY presence at app startup, before any browser construction","In CI/CD, assert required env vars before deploy","Pass apiKey explicitly from a single config module instead of relying on ambient env","Remember empty string is falsy — trim and check length"],"tags":["config","api-key","environment-variable","authentication"],"backgroundTag":"missing-env-var","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}