FirecrawlBrowser requires `apiKey` or FIRECRAWL_API_KEY

Error message

FirecrawlBrowser requires `apiKey` or FIRECRAWL_API_KEY

What it means

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.

Source

Thrown at browser/firecrawl/src/firecrawl-browser.ts:38

/**
 * Mastra browser provider backed by [Firecrawl Browser Sandbox](https://docs.firecrawl.dev/features/browser):
 * provisions remote sessions via API and drives them with the same deterministic tools as {@link AgentBrowser}.
 */
export class FirecrawlBrowser extends AgentBrowser {
  override readonly name = 'FirecrawlBrowser';
  override readonly provider = 'firecrawl/browser-sandbox';

  /** Narrowed from base `MastraBrowser` (`unknown`) — same pattern as {@link AgentBrowser}. */
  declare protected sharedManager: BrowserManager | null;

  private readonly firecrawl: Firecrawl;
  private readonly sessionOpts: FirecrawlBrowserSessionOptions;
  private sharedFirecrawlSessionId?: string;

  constructor(config: FirecrawlBrowserConfig) {
    const apiKey = config.apiKey ?? process.env.FIRECRAWL_API_KEY;
    if (!apiKey) {
      throw new Error('FirecrawlBrowser requires `apiKey` or FIRECRAWL_API_KEY');
    }
    const fc = new Firecrawl({ apiKey, apiUrl: config.apiUrl });
    const sessionOpts = pickSessionOpts(config);

    super({
      ...toBaseConfig(config),
      createThreadManager: opts =>
        new FirecrawlAgentBrowserThreadManager({
          ...opts,
          firecrawl: fc,
          resolveWebSocketUrl: url => resolveCdpWebSocketUrl(url, opts.logger),
          sessionOptions: sessionOpts,
        }),
    });
    this.firecrawl = fc;
    this.sessionOpts = sessionOpts;
  }

View on GitHub (pinned to 75dd419e61)

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

Example fix

// before
const browser = new FirecrawlBrowser({});
// after
const browser = new FirecrawlBrowser({ apiKey: process.env.FIRECRAWL_API_KEY });

Defensive patterns

Strategy: validation

Validate before calling

const apiKey = config.apiKey ?? process.env.FIRECRAWL_API_KEY;
if (!apiKey) throw new Error('Set FIRECRAWL_API_KEY or pass apiKey to FirecrawlBrowser');

Type guard

function hasFirecrawlKey(config: { apiKey?: string }): config is { apiKey: string } {
  return Boolean(config.apiKey ?? process.env.FIRECRAWL_API_KEY);
}

Try / catch

try {
  const browser = new FirecrawlBrowser(config);
} catch (e) {
  if (e instanceof Error && e.message.includes('apiKey')) {
    throw new Error('Firecrawl configuration error: missing apiKey / FIRECRAWL_API_KEY');
  }
  throw e;
}

Prevention

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

When it happens

Trigger: 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).

Common situations: 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.

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

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