mastra-ai/mastra · error · Error

Invalid arguments for firecrawl_search

Error message

Invalid arguments for firecrawl_search

What it means

The firecrawl_search tool executor validates its arguments with isSearchOptions(args) before calling the Firecrawl API. When the incoming arguments object fails that predicate — missing/invalid query, out-of-range limit, bad timeout, or wrong types for optional fields — the executor throws 'Invalid arguments for firecrawl_search' instead of making a network call. It is a pre-flight argument-shape guard, not an API error.

Source

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

        const response = await client.checkCrawlStatus(args.id);
        if (!response.success) {
          throw new Error(response.error);
        }
        const status = `Crawl Status:
Status: ${response.status}
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');

View on GitHub (pinned to 75dd419e61)

Solutions

1. Ensure args includes a non-empty string `query` field.
2. Validate numeric fields (limit, timeout) are actual numbers within allowed ranges before invoking the tool.
3. Compare your call against the firecrawl_search Zod schema in the server's tool definitions and fix the argument object.
4. If arguments come from an LLM, tighten the tool's input schema/JSON-schema so invalid args are rejected before execution.

Example fix

// before
firecrawl_search({ query: "news", limit: "5" })
// after
firecrawl_search({ query: "news", limit: 5 })

function canCallSearch(args) {
  return (
    !!args &&
    typeof args.query === 'string' &&
    args.query.trim().length > 0 &&
    (args.limit === undefined || (typeof args.limit === 'number' && args.limit > 0 && args.limit <= 100)) &&
    (args.timeout === undefined || typeof args.timeout === 'number')
  );
}
if (!canCallSearch(args)) throw new TypeError('firecrawl_search requires non-empty string query and numeric limit/timeout');

function isSearchArgs(a: unknown): a is { query: string; limit?: number; timeout?: number } {
  if (typeof a !== 'object' || a === null) return false;
  const o = a as Record<string, unknown>;
  return typeof o.query === 'string' && o.query.length > 0 &&
    (o.limit === undefined || typeof o.limit === 'number') &&
    (o.timeout === undefined || typeof o.timeout === 'number');
}

try {
  return await firecrawlSearch(args);
} catch (e) {
  if (e instanceof Error && e.message.startsWith('Invalid arguments for firecrawl_search')) {
    console.error('Bad search args, fix schema:', JSON.stringify(args));
    return { corrected: false, error: e.message };
  }
  throw e;
}

When it happens

Trigger: Calling firecrawl_search with args that fail isSearchOptions: args is null/undefined, query is missing or not a non-empty string, limit is not a number within allowed range, timeout invalid, or optional fields like scrapeOptions have wrong types.

Common situations: LLM/agent clients hallucinating malformed tool arguments; hand-written JSON args with limit as a string ('5' instead of 5); omitting query entirely; passing tbs or other option fields with wrong types after a schema change.

Related errors

• Invalid arguments for firecrawl_extract
• 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/21b09e7f04abd06c. Report an issue: GitHub.