{"record":{"id":"1ff7b9d93f5bff83","repo":"mastra-ai/mastra","slug":"knowledge-semantic-index-indexname-is-unavailab","errorCode":null,"errorMessage":"Knowledge semantic index ${indexName} is unavailable. Capture or index knowledge before searching.","messagePattern":"Knowledge semantic index (.+?) is unavailable\\. Capture or index knowledge before searching\\.","errorType":"exception","errorClass":"StaleKnowledgeSemanticIndexError","httpStatus":null,"severity":"warning","filePath":"packages/memory/src/processors/observational-memory/subconscious/semantic-index.ts","lineNumber":77,"sourceCode":"    const draining = this.#drain(scope).finally(() => {\n      this.#draining.delete(key);\n    });\n    this.#draining.set(key, draining);\n    return draining;\n  }\n\n  async search(query: string, scope: KnowledgeScope, limit = 10) {\n    await this.drain(scope);\n    const result = await this.#embedder.doEmbed({\n      values: [query],\n      ...(this.#embedderOptions ?? {}),\n    } as never);\n    const embedding = result.embeddings[0];\n    if (!embedding?.length) throw new Error('Embedder returned no vector for knowledge search query.');\n\n    const indexName = this.#indexName(embedding.length);\n    if (!(await this.#knowledgeIndexes()).includes(indexName)) {\n      throw new StaleKnowledgeSemanticIndexError(\n        `Knowledge semantic index ${indexName} is unavailable. Capture or index knowledge before searching.`,\n      );\n    }\n\n    const visibleScopeKeys = scope.map((_, index) => scope.slice(0, index + 1).join('\\u001f'));\n    const batches = await Promise.all(\n      visibleScopeKeys.map(scopeKey =>\n        this.#vector.query({\n          indexName,\n          queryVector: embedding,\n          topK: limit,\n          filter: { scope_key: scopeKey },\n        }),\n      ),\n    );\n    const deduped = new Map<string, (typeof batches)[number][number]>();\n    for (const candidate of batches.flat()) {\n      const candidateScope = candidate.metadata?.scope;","sourceCodeStart":59,"sourceCodeEnd":95,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/memory/src/processors/observational-memory/subconscious/semantic-index.ts#L59-L95","documentation":"After embedding the query, `search` (semantic-index.ts:77) verifies that a vector index matching the embedding dimension (`this.#indexName(embedding.length)`) exists among the knowledge indexes. If not, it throws `StaleKnowledgeSemanticIndexError`: no index exists for this dimension, meaning no knowledge has been captured or indexed for the current scope, so search results would be meaningless.","triggerScenarios":"Searching before any document was ever indexed for the embedding dimension (index name absent from `#knowledgeIndexes()`); switching embedders to a different dimension (e.g. 1536 -> 768) so the new dimension's index was never created; searching a fresh scope/database with no captured knowledge.","commonSituations":"Deploying search against a brand-new database; swapping embedding models (different vector dimension) without re-indexing; pointing at a different environment's storage where no knowledge exists.","solutions":["Capture/index knowledge first (run the observation/indexing pipeline) so the semantic index for your embedder's dimension is created.","Re-index existing documents after changing the embedding model/dimension, or revert to the original embedder.","Confirm you are connected to the intended storage environment that already contains the knowledge index."],"exampleFix":"// before (searching a fresh DB)\nawait remind(context); // StaleKnowledgeSemanticIndexError\n// after — index first\nawait semanticIndexer.capture(documents);\nawait semanticIndexer.search(scope, query);","handlingStrategy":"try-catch","validationCode":"const store = await memory.storage.getStore('knowledge');\nconst indexes = await store.listVectorIndexes?.() ?? [];\n// if your embedder dimension is 1536, an index for that dimension must exist before searching\nif (!indexes.some((n) => n.includes('1536'))) console.warn('knowledge semantic index missing — capture/index knowledge first');","typeGuard":"function indexExistsForDimension(indexNames, dimension) {\n  return indexNames.includes(`knowledge_${dimension}`); // adjust to your #indexName convention\n}","tryCatchPattern":"try {\n  return await remind(context);\n} catch (e) {\n  if (e instanceof StaleKnowledgeSemanticIndexError && e.message.includes('is unavailable')) {\n    logger.info('no knowledge indexed yet for this scope; skipping remind');\n    return;\n  }\n  throw e;\n}","preventionTips":["Run the capture/indexing pipeline before enabling remind in production.","When changing embedding models, re-index and verify the new dimension's index exists.","Confirm you point at the intended environment's storage."],"tags":["semantic-index","stale-index","embeddings"],"backgroundTag":"stale-semantic-index","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}