{"record":{"id":"9021b68089a2202c","repo":"mastra-ai/mastra","slug":"vector-search-requires-vector-configuration","errorCode":null,"errorMessage":"Vector search requires vector configuration.","messagePattern":"Vector search requires vector configuration\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/workspace/search/search-engine.ts","lineNumber":650,"sourceCode":"\n  /**\n   * Get the BM25 index (for serialization/debugging)\n   */\n  get bm25Index(): BM25Index | undefined {\n    return this.#bm25Index;\n  }\n\n  // ===========================================================================\n  // Private Methods\n  // ===========================================================================\n\n  /**\n   * Determine the effective search mode\n   */\n  #determineSearchMode(requestedMode?: SearchMode): SearchMode {\n    if (requestedMode) {\n      if (requestedMode === 'vector' && !this.canVector) {\n        throw new Error('Vector search requires vector configuration.');\n      }\n      if (requestedMode === 'bm25' && !this.canBM25) {\n        throw new Error('BM25 search requires BM25 configuration.');\n      }\n      if (requestedMode === 'hybrid' && !this.canHybrid) {\n        throw new Error('Hybrid search requires both vector and BM25 configuration.');\n      }\n      return requestedMode;\n    }\n\n    // Auto-determine based on available configuration\n    if (this.canHybrid) {\n      return 'hybrid';\n    }\n    if (this.canVector) {\n      return 'vector';\n    }\n    if (this.canBM25) {","sourceCodeStart":632,"sourceCodeEnd":668,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workspace/search/search-engine.ts#L632-L668","documentation":"#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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Omit the mode or request 'bm25' so the engine uses its configured BM25 index.","Add vector configuration (embedder + vector store) to the engine at construction.","Gate the mode choice on engine capability (canVector) before requesting vector search."],"exampleFix":"// before\nawait engine.search(query, { mode: 'vector' });\n// after\nconst mode = engine.canVector ? 'vector' : 'bm25';\nawait engine.search(query, { mode });","handlingStrategy":"fallback","validationCode":"function canUseMode(engine: { canVector: boolean; canBM25: boolean }, mode?: string): boolean {\n  if (mode === 'vector') return engine.canVector;\n  if (mode === 'bm25') return engine.canBM25;\n  if (mode === 'hybrid') return engine.canHybrid;\n  return true;\n}","typeGuard":"function supportsVectorMode(engine: object): boolean {\n  return (engine as any).canVector === true;\n}","tryCatchPattern":"try {\n  return await engine.search(q, { mode: requestedMode });\n} catch (e) {\n  if (e instanceof Error && /Vector search requires vector configuration/.test(e.message)) {\n    return engine.search(q, { mode: 'bm25' }); // graceful downgrade\n  }\n  throw e;\n}","preventionTips":["Choose search mode from engine capability flags (canVector/canBM25/canHybrid), not hardcoded values.","Configure the embedder and vector store at engine construction if vector search is required.","Centralize mode selection in one helper so all call sites degrade consistently."],"tags":["search","vector","configuration","validation"],"backgroundTag":"feature-not-configured","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}