What causes "query is required for mode="search"" in mastra-ai/mastra?

Ensure prompts/tool descriptions guide the model to always supply a query when mode='search'.

query is required for mode="search"

Error message

query is required for mode="search"

What it means

In the recall tool's search mode (om-tools.ts:1385-1387), query is mandatory: semantic search forwards it to Memory.searchMessages. This runtime guard exists because input validation can be skipped on resumed runs and builder-validated input, so a search call without a query string would otherwise crash deeper in the stack; the tool throws this explicit error instead.

Source

Thrown at packages/memory/src/tools/om-tools.ts:1386

      if (!memory) {
        throw new Error('Memory instance is required for recall');
      }

      if (explicitThreadId === 'current' && !currentThreadId) {
        throw new Error('Could not resolve current thread.');
      }

      // Search mode
      if (mode === 'search') {
        // Schema validation rejects mode="search" when search is disabled, but
        // validation is skipped for resumed runs and builder-validated input —
        // a stale search call on those paths would otherwise reach
        // Memory.searchMessages and throw. Return guidance instead.
        if (!searchEnabled) {
          return { results: SEARCH_NOT_CONFIGURED_MESSAGE, count: 0 };
        }
        if (!query) {
          throw new Error('query is required for mode="search"');
        }
        if (!resourceId) {
          throw new Error('Resource ID is required for recall');
        }
        return searchMessagesForResource({
          memory,
          resourceId,
          currentThreadId: currentThreadId || undefined,
          query,
          topK: limit ?? 10,
          before,
          after,
          threadScope: !isResourceScope ? currentThreadId || undefined : resolvedExplicitThreadId || undefined,
        });
      }

      // Thread listing mode
      if (mode === 'threads') {

View on GitHub (pinned to 75dd419e61)

Solutions

Ensure prompts/tool descriptions guide the model to always supply a query when mode='search'.
In code that invokes the tool programmatically, include query: recallToolArgs = { mode: 'search', query: '...' }.
Catch the error in a tool-middleware and re-prompt the model to provide a search term.
On resumed runs, re-validate inputData (query non-empty string) before executing the search branch.

Example fix

// before
await tool.execute({ mode: 'search' });
// after
if (args.mode === 'search' && !args.query) {
  throw new Error('mode="search" requires a non-empty query');
}
await tool.execute(args);

Defensive patterns

Strategy: validation

Validate before calling

// before executing a search-mode recall call
if (args.mode === 'search' && (typeof args.query !== 'string' || args.query.trim().length === 0)) {
  throw new Error('mode="search" requires a non-empty query');
}

Type guard

function isSearchInput(
  args: { mode?: string; query?: string }
): args is { mode: 'search'; query: string } {
  return args.mode === 'search' && typeof args.query === 'string' && args.query.trim().length > 0;
}

Try / catch

try {
  return await recallExecute(inputData, context);
} catch (err) {
  if (err instanceof Error && err.message.includes('query is required')) {
    return { error: 'Provide a search query when using mode="search".' };
  }
  throw err;
}

Prevention

Re-validate inputData on resumed/replayed tool runs even if schema validation ran originally.
Write tool descriptions that require query for search so models supply it.
Sanitize empty/whitespace queries to undefined upstream and handle once.

When it happens

Trigger: LLM invokes the recall tool with mode='search' but no query (or empty query) in inputData on a path where JSON-schema validation was bypassed (resumed workflows, pre-validated tool args).

Common situations: Model hallucinating incomplete tool arguments; persisted/resumed agent runs replaying a search call with truncated input; programmatic tool invocation constructing inputData by hand without query; prompt designs that encourage search without a search term.

Understand the failure class

Background: Missing required parameter errors: what 'X is required' and 'the required X param is missing' mean, and how to fix them — this error's family across 27 libraries.

Related errors

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