mastra-ai/mastra · error

BM25 search requires BM25 configuration.

Error message

BM25 search requires BM25 configuration.

What it means

SearchEngine was explicitly asked to run a 'bm25' search, but no BM25 index was ever configured on the engine. The engine validates the requested search mode against its available configuration before searching; keyword search requires a BM25 config (or a BM25 index built during indexing), so it throws instead of silently returning empty results.

Source

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

   */
  get bm25Index(): BM25Index | undefined {
    return this.#bm25Index;
  }

  // ===========================================================================
  // 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';
    }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Pass a BM25SearchConfig (bm25/tokenizer options) when constructing SearchEngine so a BM25 index is created.
2. Drop the explicit `mode: 'bm25'` from the search options and let the engine auto-select the mode, or request a mode that matches the configured backend.
3. Check `engine.canBM25` before requesting bm25 mode and branch to an available mode (e.g. vector).

Example fix

// before
await searchEngine.search('query', { mode: 'bm25' });

// after (either configure BM25)
const engine = new SearchEngine({ bm25: {}, vectorConfig: myVectorConfig });
await engine.search('query', { mode: 'bm25' });

// ...or search in an available mode
const mode = engine.canBM25 ? 'bm25' : 'vector';
await searchEngine.search('query', { mode });

if (!engine.canBM25) {
  throw new Error('This engine is not configured for BM25 search; configure a bm25 config or use another mode.');
}
await engine.search(query, { mode: 'bm25' });

When it happens

Trigger: Calling `searchEngine.search(query, { mode: 'bm25' })` (or a Workspace search API passing mode: 'bm25') on an engine constructed without a BM25SearchConfig — i.e. `canBM25` is false because the internal #bm25Index was never created.

Common situations: Constructing SearchEngine with only vectorConfig while later code (often copied from keyword-search examples) requests mode: 'bm25'; switching search modes via a UI/flag that doesn't match the deployment's config; a refactor that dropped the bm25 option from the constructor.

Related errors

• Hybrid search requires both vector and 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/1ccad64f8fbeda77. Report an issue: GitHub.