mastra-ai/mastra · error · Error

${extractResponse.error || 'Extraction failed'}

Error message

${extractResponse.error || 'Extraction failed'}

What it means

The extract operation's response from client.extract() (via withRetry) is checked for `success` in response and response.success. When the Firecrawl extract API reports failure, the server throws the API-provided error message or the fallback 'Extraction failed'. Extract is an asynchronous job endpoint, so failures also occur when the job is not found, times out, or is cancelled.

Source

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

          const extractStartTime = Date.now();

          safeLog('info', `Starting extraction for URLs: ${args.urls.join(', ')}`);

          const extractResponse = await withRetry(
            async () =>
              client.extract(args.urls, {
                prompt: args.prompt,
                systemPrompt: args.systemPrompt,
                schema: args.schema,
                allowExternalLinks: args.allowExternalLinks,
                enableWebSearch: args.enableWebSearch,
                includeSubdomains: args.includeSubdomains,
              } as ExtractParams),
            'extract operation',
          );

          if (!('success' in extractResponse) || !extractResponse.success) {
            throw new Error(extractResponse.error || 'Extraction failed');
          }

          const response = extractResponse as ExtractResponse;

          safeLog('info', `Extraction completed in ${Date.now() - extractStartTime}ms`);

          const result = {
            content: [
              {
                type: 'text',
                text: trimResponseText(JSON.stringify(response.data, null, 2)),
              },
            ],
            isError: false,
          };

          if (response.warning) {
            safeLog('warning', response.warning);

View on GitHub (pinned to 75dd419e61)

Solutions

1. Read extractResponse.error for the underlying cause (auth, credits, invalid URL, job state).
2. Verify API key validity and remaining extract credits in the Firecrawl dashboard.
3. Retry with ignoreInvalidURLs: true so bad URLs don't fail the whole extract job.
4. Increase poll/timeout parameters and re-check job status if the job timed out before completion.

Example fix

// before
if (!('success' in extractResponse) || !extractResponse.success) {
  throw new Error(extractResponse.error || 'Extraction failed');
}
// after
if (!('success' in extractResponse) || !extractResponse.success) {
  logger.error('extract failed', extractResponse.error);
  const retryable = /429|timeout|temporarily/i.test(extractResponse.error ?? '');
  if (retryable) return retryExtractLater(args);
  throw new Error(`Extraction failed: ${extractResponse.error ?? 'no detail from API'}`);
}

// Pre-flight prerequisites for extract jobs:
if (!process.env.FIRECRAWL_API_KEY) throw new Error('FIRECRAWL_API_KEY missing');
const urlRe = /^https?:\/\//;
if (!args.urls.every(u => urlRe.test(u))) throw new TypeError('all urls must be absolute http(s) URLs');

function isExtractSuccess(res: unknown): res is { success: true; data: unknown } {
  return typeof res === 'object' && res !== null &&
    'success' in res && (res as any).success === true;
}

try {
  const res = await firecrawlExtract(args);
  if (!res.success) throw new Error(res.error || 'Extraction failed');
} catch (e) {
  const msg = e instanceof Error ? e.message : String(e);
  if (/429|timeout|temporarily|job/i.test(msg)) return withBackoff(() => firecrawlExtract(args), 3);
  if (/401|403|credit/i.test(msg)) throw new Error('Firecrawl auth/credits problem: ' + msg);
  throw e;
}

When it happens

Trigger: extractResponse.success is falsy or the response lacks a success field — invalid API key, rate limits, invalid URLs rejected server-side, extract job failed/expired/not found, or a timeout while withRetry still returned a non-success envelope.

Common situations: Extracting from sites that block scraping or require JS login; job submitted but poll expired before completion; credits exhausted for the batch of URLs; older SDK versions returning responses without the success field.

Related errors

• ${response.error || 'LLMs.txt generation failed'}
• Search failed: ${response.error || 'Unknown error'}
• ${response.error || 'Deep research failed'}
• Token exchange failed: ${error}
• Google Directory groups.list failed (${response.status}): ${

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