mastra-ai/mastra · error

Vector search requires vector configuration.

Error message

Vector search requires vector configuration.

What it means

#determineSearchMode validates an explicitly requested search mode against the engine's configuration. Requesting 'vector' (via effectiveMode) when the engine was constructed without vector configuration (no embedder/vector store) cannot be honored, so it throws instead of silently downgrading to another mode.

Solutions

1. Omit the mode or request 'bm25' so the engine uses its configured BM25 index.
2. Add vector configuration (embedder + vector store) to the engine at construction.
3. Gate the mode choice on engine capability (canVector) before requesting vector search.

Example fix

// before
await engine.search(query, { mode: 'vector' });
// after
const mode = engine.canVector ? 'vector' : 'bm25';
await engine.search(query, { mode });

function canUseMode(engine: { canVector: boolean; canBM25: boolean }, mode?: string): boolean {
  if (mode === 'vector') return engine.canVector;
  if (mode === 'bm25') return engine.canBM25;
  if (mode === 'hybrid') return engine.canHybrid;
  return true;
}

function supportsVectorMode(engine: object): boolean {
  return (engine as any).canVector === true;
}

try {
  return await engine.search(q, { mode: requestedMode });
} catch (e) {
  if (e instanceof Error && /Vector search requires vector configuration/.test(e.message)) {
    return engine.search(q, { mode: 'bm25' }); // graceful downgrade
  }
  throw e;
}

When it happens

Trigger: Calling search({ mode: 'vector' }) (or an API defaulting to vector) on a search engine built with only BM25 configuration — e.g. no embeddings/embedder supplied at construction, or vector deps not installed/configured.

Common situations: Copying search code between projects where the target engine lacks vector config; toggling mode from an env/CLI flag on a BM25-only deployment; expecting automatic embedding setup that was never configured.

Related errors

• A custom capture schema requires an onExtracted hook that…
• BM25 search requires BM25 configuration.
• Both baselineResponse and noisyQuery are required for Noise…
• Built-in Subconscious reflection agent
• Chunk overlap ( ) must be smaller than chunk size ( ).

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

Appendix: source

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

  /**
   * Get the BM25 index (for serialization/debugging)
   */
  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) {

View on GitHub (pinned to 75dd419e61)