mastra-ai/mastra · error · Error

Invalid arguments for firecrawl_deep_research

Error message

Invalid arguments for firecrawl_deep_research

What it means

firecrawl_deep_research has no dedicated predicate; it manually checks that args is a non-null object containing a `query` key, throwing this error otherwise. Deep research drives a long-running multi-step Firecrawl job, so the guard ensures a research query actually exists before spending API credits.

Source

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

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

          return result;
        } catch (error) {
          const errorMessage = error instanceof Error ? error.message : String(error);

          return {
            content: [{ type: 'text', text: trimResponseText(errorMessage) }],
            isError: true,
          };
        }
      }

      case 'firecrawl_deep_research': {
        if (!args || typeof args !== 'object' || !('query' in args)) {
          throw new Error('Invalid arguments for firecrawl_deep_research');
        }

        try {
          const researchStartTime = Date.now();
          safeLog('info', `Starting deep research for query: ${args.query}`);

          const response = await client.deepResearch(
            args.query as string,
            {
              maxDepth: args.maxDepth as number,
              timeLimit: args.timeLimit as number,
              maxUrls: args.maxUrls as number,
            },
            activity => {
              safeLog('info', `Research activity: ${activity.message} (Depth: ${activity.depth})`);
            },
            source => {
              safeLog('info', `Research source found: ${source.url}${source.title ? ` - ${source.title}` : ''}`);

View on GitHub (pinned to 75dd419e61)

Solutions

1. Always pass `query` as a non-empty string: { query: "your research question" }.
2. Check for typos in the parameter name (must be exactly `query`).
3. Review the firecrawl_deep_research tool schema to confirm required fields for your server version.
4. If an LLM generates the args, include the query field explicitly in the prompt/template or schema example.

Example fix

// before
firecrawl_deep_research({ maxDepth: 3 })
// after
firecrawl_deep_research({ query: "state of AI regulation 2026", maxDepth: 3 })

function canCallDeepResearch(args) {
  return (
    !!args &&
    typeof args === 'object' &&
    'query' in args &&
    typeof args.query === 'string' &&
    args.query.trim().length > 0
  );
}
if (!canCallDeepResearch(args)) throw new TypeError('firecrawl_deep_research requires a non-empty string query');

function isDeepResearchArgs(a: unknown): a is { query: string; maxDepth?: number; maxUrls?: number; timeLimit?: number } {
  return typeof a === 'object' && a !== null && 'query' in a &&
    typeof (a as any).query === 'string' && (a as any).query.length > 0;
}

try {
  return await firecrawlDeepResearch(args);
} catch (e) {
  if (e instanceof Error && e.message.includes('Invalid arguments for firecrawl_deep_research')) {
    console.error('deep_research args must include query; got:', JSON.stringify(args));
    throw new TypeError('Provide { query: string } to firecrawl_deep_research');
  }
  throw e;
}

When it happens

Trigger: args is null/undefined, not an object, or lacks a `query` property — e.g. calling the tool with {}, with only optional params like maxDepth/maxUrls, or with the query field misspelled (q, topic, question).

Common situations: LLM client calls the tool with only optional parameters; client code renamed the field after a schema update; arguments dropped in transport so an empty object arrives.

Related errors

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