mastra-ai/mastra · error · Error

Search failed: ${response.error || 'Unknown error'}

Error message

Search failed: ${response.error || 'Unknown error'}

What it means

After calling client.search() (wrapped in withRetry), the executor checks response.success. Firecrawl v1 API returns { success: false, error: string } on failure, and this code rethrows the API's error message, defaulting to 'Unknown error' when the error field is absent. This is a server-side/API failure surfaced through the SDK response object.

Source

Thrown at packages/mcp/src/__fixtures__/fire-crawl-complex-schema.ts:759

Progress: ${response.completed}/${response.total}
Credits Used: ${response.creditsUsed}
Expires At: ${response.expiresAt}
${response.data.length > 0 ? '\nResults:\n' + formatResults(response.data) : ''}`;
        return {
          content: [{ type: 'text', text: trimResponseText(status) }],
          isError: false,
        };
      }

      case 'firecrawl_search': {
        if (!isSearchOptions(args)) {
          throw new Error('Invalid arguments for firecrawl_search');
        }
        try {
          const response = await withRetry(async () => client.search(args.query, { ...args }), 'search operation');

          if (!response.success) {
            throw new Error(`Search failed: ${response.error || 'Unknown error'}`);
          }

          const results = response.data
            .map(
              result =>
                `URL: ${result.url}
Title: ${result.title || 'No title'}
Description: ${result.description || 'No description'}
${result.markdown ? `\nContent:\n${result.markdown}` : ''}`,
            )
            .join('\n\n');

          return {
            content: [{ type: 'text', text: trimResponseText(results) }],
            isError: false,
          };
        } catch (error) {
          const errorMessage = error instanceof Error ? error.message : `Search failed: ${JSON.stringify(error)}`;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Inspect response.error (or enable logging) to get the real API error message.
2. Verify FIRECRAWL_API_KEY is set and valid; check billing/credits on the Firecrawl dashboard.
3. Check https://status.firecrawl.dev for outages and retry after backoff for 429/5xx.
4. Confirm SDK version matches the v1 API and that search options are supported.

Example fix

// before
if (!response.success) {
  throw new Error(`Search failed: ${response.error || 'Unknown error'}`);
}
// after
if (!response.success) {
  const msg = response.error || 'Unknown error';
  if (/401|unauthorized/i.test(msg)) throw new Error('Check FIRECRAWL_API_KEY: ' + msg);
  if (/429|rate/i.test(msg)) await new Promise(r => setTimeout(r, 2000)); // then retry
  throw new Error(`Search failed: ${msg}`);
}

// Cannot fully pre-validate (server-side), but ensure prerequisites:
if (!process.env.FIRECRAWL_API_KEY) throw new Error('FIRECRAWL_API_KEY is not set');
if (typeof args?.query !== 'string' || !args.query.trim()) throw new TypeError('query must be a non-empty string');

function isSearchFailure(res: unknown): res is { success: false; error?: string } {
  return typeof res === 'object' && res !== null &&
    (res as any).success === false;
}

try {
  const res = await firecrawlSearch(args);
  if (!res.success) throw new Error(`Search failed: ${res.error ?? 'Unknown error'}`);
} catch (e) {
  const msg = e instanceof Error ? e.message : String(e);
  if (/401|403|unauthorized/i.test(msg)) throw new Error('Firecrawl auth failed - check FIRECRAWL_API_KEY');
  if (/429|rate limit/i.test(msg)) throw new RetryableError(msg); // retry with backoff
  throw e;
}

When it happens

Trigger: The Firecrawl search API returns success:false — invalid or missing FIRECRAWL_API_KEY, rate limiting (429), insufficient credits, Firecrawl service outage (5xx), or an invalid combination of search options rejected server-side.

Common situations: Expired or revoked API key; free-plan credit exhaustion; searching while Firecrawl is degraded; passing scrapeOptions the API version does not support; error field missing so the message is just 'Search failed: Unknown error'.

Related errors

• ${extractResponse.error || 'Extraction failed'}
• ${response.error || 'Deep research failed'}
• ${response.error || 'LLMs.txt generation failed'}
• Token exchange failed: ${error}
• Token exchange failed: ${error}

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