mastra-ai/mastra · warning · HTTPException

Search query is required

Error message

Search query is required

What it means

The workspace search handler (GET /api/workspaces/:workspaceId/search) throws this 400 when the `query` parameter is missing or empty. Search requires a non-empty query string to pass to workspace.search(). This is a request-validation guard before any workspace lookup occurs.

Source

Thrown at packages/server/src/server/handlers/workspace.ts:770

// Search Routes
// =============================================================================

export const WORKSPACE_SEARCH_ROUTE = createRoute({
  method: 'GET',
  path: '/workspaces/:workspaceId/search',
  responseType: 'json',
  pathParamSchema: workspaceIdPathParams,
  queryParamSchema: searchQuerySchema,
  responseSchema: searchResponseSchema,
  summary: 'Search workspace content',
  description: 'Searches across indexed workspace content using BM25, vector, or hybrid search',
  tags: ['Workspace'],
  handler: async ({ mastra, query, topK, mode, minScore, workspaceId }) => {
    try {
      requireWorkspaceV1Support();

      if (!query) {
        throw new HTTPException(400, { message: 'Search query is required' });
      }

      const workspace = await getWorkspaceById(mastra, workspaceId);
      if (!workspace) {
        return {
          results: [],
          query,
          mode: mode || 'bm25',
        };
      }

      // Check search capabilities
      const canSearch = workspace.canBM25 || workspace.canVector;
      if (!canSearch) {
        return {
          results: [],
          query,
          mode: mode || 'bm25',

View on GitHub (pinned to 75dd419e61)

Solutions

1. Include a non-empty `query` query parameter in the request.
2. In the UI, disable or skip the search request until input is non-empty.
3. If a blank search should return all/no results, handle that client-side instead of calling the endpoint.

Example fix

// before
const url = `/api/workspaces/ws1/search?topK=5`;
// after
const url = `/api/workspaces/ws1/search?query=${encodeURIComponent(term)}&topK=5`;

if (typeof query !== 'string' || query.trim() === '') {
  throw new Error('query is required before calling workspace search');
}

function hasQuery(q: unknown): q is string {
  return typeof q === 'string' && q.trim().length > 0;
}

try {
  const results = await searchWorkspace(wsId, query);
} catch (e) {
  if (isHTTPException(e, 400) && e.message === 'Search query is required') {
    return { results: [], query: '' }; // degrade gracefully for empty input
  }
  throw e;
}

When it happens

Trigger: Calling GET /workspaces/:workspaceId/search without a `query` query parameter, with `?query=` (empty string), or with a client that strips empty query params — e.g. building the URL conditionally and omitting query when the user's search box is empty.

Common situations: UI sending the search request before the user types anything; a template-literal URL with an undefined variable; HTTP clients that drop null/undefined params; wrappers around the Mastra client with default-empty arguments.

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

• runId required to stream workflow
• runId required to resume workflow
• runId required to start run
• runId required to time travel workflow stream
• runId required to cancel workflow run

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