mastra-ai/mastra · error

notification-inbox search requires query

Error message

notification-inbox search requires query

What it means

The search action of the notification-inbox tool requires a non-empty query string. Without it the tool would perform an unbounded listing, so the library throws to force the caller to specify what to search for.

Source

Thrown at packages/core/src/notifications/tool.ts:114

    execute: async (input: NotificationInboxAction, context) => {
      const threadId = input.threadId ?? context?.agent?.threadId;
      if (!threadId) {
        throw new Error('notification-inbox requires a threadId');
      }

      if (input.action === 'list') {
        const listInput: ListNotificationsInput = {
          threadId,
          status: input.status,
          priority: input.priority,
          source: input.source,
          limit: input.limit,
        };
        return { notifications: await storage.listNotifications(listInput) };
      }

      if (input.action === 'search') {
        if (!input.query) throw new Error('notification-inbox search requires query');
        return {
          notifications: await storage.listNotifications({
            threadId,
            search: input.query,
            status: input.status,
            priority: input.priority,
            source: input.source,
            limit: input.limit,
          }),
        };
      }

      if (input.action === 'read') {
        const notifications = input.id
          ? [await storage.getNotification({ threadId, id: input.id })]
          : await storage.listNotifications({
              threadId,
              status: input.status ?? ['pending', 'delivered'],

View on GitHub (pinned to 75dd419e61)

Solutions

1. Always supply a non-empty query when using action 'search'
2. Fall back to action 'list' when the query is empty
3. Validate user-supplied search input before mapping it to the tool action

Example fix

// before
await inboxTool.execute({ action: 'search', threadId, query: '' });
// after
const action = query.trim() ? 'search' : 'list';
await inboxTool.execute({ action, threadId, ...(query.trim() ? { query: query.trim() } : {}) });

if (input.action === 'search' && !input.query?.trim()) {
  input = { ...input, action: 'list' };
}

function isSearchAction(i: NotificationInboxAction): i is Extract<NotificationInboxAction, { action: 'search'; query: string }> {
  return i.action === 'search' && typeof (i as any).query === 'string' && (i as any).query.length > 0;
}

try {
  return await inboxTool.execute(input, context);
} catch (e) {
  if (e instanceof Error && e.message.includes('search requires query')) {
    return await inboxTool.execute({ ...input, action: 'list' } as NotificationInboxAction, context);
  }
  throw e;
}

When it happens

Trigger: Invoking the tool with action 'search' but omitting input.query or passing an empty string (e.g. forwarding user input where the search box was blank).

Common situations: LLM-filled tool args where the model emitted action 'search' without query; UI passing empty search text straight to the tool instead of falling back to the 'list' action.

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

• notification-inbox requires a threadId
• Notification ${input.id} was not found for thread ${threadId
• notification-inbox ${input.action} requires id
• Invalid notification dispatch time: ${input}
• Tool must have input and output schemas defined

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