mastra-ai/mastra · error · Error

Invalid arguments for firecrawl_extract

Error message

Invalid arguments for firecrawl_extract

What it means

The firecrawl_extract tool validates args with isExtractOptions(args) before executing. Extraction requires a non-empty `urls` array of valid http(s) URLs plus optional boolean/enum fields; failing that shape throws this error before any API request. Like the other firecrawl guards, it exists because MCP clients can send arbitrary JSON as tool arguments.

Source

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

            )
            .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)}`;
          return {
            content: [{ type: 'text', text: trimResponseText(errorMessage) }],
            isError: true,
          };
        }
      }

      case 'firecrawl_extract': {
        if (!isExtractOptions(args)) {
          throw new Error('Invalid arguments for firecrawl_extract');
        }

        try {
          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',

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass urls as a non-empty array of valid http(s) URL strings.
2. Ensure optional flags (includeSubdomains, ignoreInvalidURLs, waitFor, etc.) have correct types per isExtractOptions.
3. Check the firecrawl_extract tool's Zod input schema and align your arguments exactly.
4. For LLM callers, add a JSON-schema precondition so invalid extract args are corrected before tool execution.

Example fix

// before
firecrawl_extract({ urls: "https://a.com,https://b.com" })
// after
firecrawl_extract({ urls: ["https://a.com", "https://b.com"], includeSubdomains: false })

function canCallExtract(args) {
  return (
    !!args &&
    Array.isArray(args.urls) &&
    args.urls.length > 0 &&
    args.urls.every(u => {
      try { const p = new URL(u); return p.protocol === 'http:' || p.protocol === 'https:'; }
      catch { return false; }
    }) &&
    (args.includeSubdomains === undefined || typeof args.includeSubdomains === 'boolean') &&
    (args.ignoreInvalidURLs === undefined || typeof args.ignoreInvalidURLs === 'boolean')
  );
}

function isExtractArgs(a: unknown): a is { urls: string[]; includeSubdomains?: boolean; ignoreInvalidURLs?: boolean } {
  if (typeof a !== 'object' || a === null) return false;
  const o = a as Record<string, unknown>;
  return Array.isArray(o.urls) && o.urls.length > 0 && o.urls.every((u): u is string => typeof u === 'string') &&
    (o.includeSubdomains === undefined || typeof o.includeSubdomains === 'boolean');
}

try {
  return await firecrawlExtract(args);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Invalid arguments for firecrawl_extract')) {
    // normalize common mistakes: string -> array
    if (typeof args?.urls === 'string') return firecrawlExtract({ ...args, urls: args.urls.split(',').map(s => s.trim()) });
    throw new TypeError('extract needs urls: string[] of http(s) URLs');
  }
  throw e;
}

When it happens

Trigger: args fails isExtractOptions: urls missing, not an array, empty array, or containing non-URL strings; includeSubdomains/ignoreInvalidURLs present but not booleans; prompt or schema fields of wrong type.

Common situations: Client sends urls as a comma-separated string instead of an array; LLM produces a single string for urls; schema/prompt passed as JSON string instead of object; forgetting that extract requires at least one URL or a prompt.

Related errors

• Invalid arguments for firecrawl_search
• Invalid arguments for firecrawl_deep_research
• Invalid arguments for firecrawl_generate_llmstxt
• No arguments provided
• Invalid arguments for firecrawl_scrape

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