{"record":{"id":"d35303680b55e9c1","repo":"mastra-ai/mastra","slug":"hybrid-search-requires-both-vector-and-bm25-config","errorCode":null,"errorMessage":"Hybrid search requires both vector and BM25 configuration.","messagePattern":"Hybrid search requires both vector and BM25 configuration\\.","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/core/src/workspace/search/search-engine.ts","lineNumber":656,"sourceCode":"  }\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) {\n      return 'bm25';\n    }\n\n    throw new Error('No search configuration available. Provide bm25 or vector config.');\n  }\n","sourceCodeStart":638,"sourceCodeEnd":674,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/core/src/workspace/search/search-engine.ts#L638-L674","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Provide both BM25 config and vector config (vector store + embedder + indexName) to the SearchEngine so `canHybrid` is true.","Remove the explicit `mode: 'hybrid'` and let the engine auto-determine the best available mode.","Gate the hybrid call on `engine.canHybrid` and fall back to 'vector' or 'bm25' when false."],"exampleFix":"// before\nawait engine.search(q, { mode: 'hybrid' }); // throws in vector-only setup\n\n// after\nif (!engine.canHybrid) {\n  await engine.search(q); // engine picks the best available mode\n} else {\n  await engine.search(q, { mode: 'hybrid' });\n}","handlingStrategy":"validation","validationCode":"if (mode === 'hybrid' && !engine.canHybrid) {\n  mode = engine.canVector ? 'vector' : 'bm25';\n}\nawait engine.search(query, { mode });","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Check `canHybrid` before requesting hybrid mode and degrade to the available single backend.","Keep engine construction and mode selection in one config-driven place.","In shared helpers, treat mode as a preference, not a requirement, unless the caller asserts availability."],"tags":["search","configuration","hybrid-search","misconfiguration"],"backgroundTag":"search-mode-not-configured","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}