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.

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)

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

• Google RBAC roleMapping is required.
• Cookie password must be at least 32 characters. Set OKTA_COO
• heartbeatMs must be a finite number no greater than ${MAX_TI
• Expected a PEM-encoded public key or certificate string for
• terminationGraceMs must be greater than zero.

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