mastra-ai/mastra · error

Hybrid search requires both vector and BM25 configuration.

Error message

Hybrid search requires both vector and BM25 configuration.

What it means

The caller requested `mode: 'hybrid'`, which fuses BM25 keyword scoring with vector similarity, but the engine lacks one of the two required backends (hybrid needs both `canBM25` and `canVector` to be true). The engine refuses instead of degrading to a partial result the caller didn't ask for.

Source

Thrown at packages/core/src/workspace/search/search-engine.ts:656

  }

  // ===========================================================================
  // Private Methods
  // ===========================================================================

  /**
   * Determine the effective search mode
   */
  #determineSearchMode(requestedMode?: SearchMode): SearchMode {
    if (requestedMode) {
      if (requestedMode === 'vector' && !this.canVector) {
        throw new Error('Vector search requires vector configuration.');
      }
      if (requestedMode === 'bm25' && !this.canBM25) {
        throw new Error('BM25 search requires BM25 configuration.');
      }
      if (requestedMode === 'hybrid' && !this.canHybrid) {
        throw new Error('Hybrid search requires both vector and BM25 configuration.');
      }
      return requestedMode;
    }

    // Auto-determine based on available configuration
    if (this.canHybrid) {
      return 'hybrid';
    }
    if (this.canVector) {
      return 'vector';
    }
    if (this.canBM25) {
      return 'bm25';
    }

    throw new Error('No search configuration available. Provide bm25 or vector config.');
  }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Provide both BM25 config and vector config (vector store + embedder + indexName) to the SearchEngine so `canHybrid` is true.
2. Remove the explicit `mode: 'hybrid'` and let the engine auto-determine the best available mode.
3. Gate the hybrid call on `engine.canHybrid` and fall back to 'vector' or 'bm25' when false.

Example fix

// before
await engine.search(q, { mode: 'hybrid' }); // throws in vector-only setup

// after
if (!engine.canHybrid) {
  await engine.search(q); // engine picks the best available mode
} else {
  await engine.search(q, { mode: 'hybrid' });
}

if (mode === 'hybrid' && !engine.canHybrid) {
  mode = engine.canVector ? 'vector' : 'bm25';
}
await engine.search(query, { mode });

When it happens

Trigger: Calling `search(query, { mode: 'hybrid' })` when the engine was constructed with only a vectorConfig (no BM25 config) or only a BM25 config (no vectorConfig/embedder/vector store).

Common situations: Keyword-only search deployments upgraded to code that defaults to hybrid; vector-only setups (embedder + vector store but no BM25 index); shared search-helper functions that hardcode hybrid mode for all engines.

Related errors

• BM25 search requires BM25 configuration.
• No search configuration available. Provide bm25 or vector co
• Vector search requires vector configuration.
• Vector configuration is required to embed text.
• Workspace does not have search configured

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