mastra-ai/mastra · warning · StaleKnowledgeSemanticIndexError

Knowledge semantic index ${indexName} is unavailable. Captur

Error message

Knowledge semantic index ${indexName} is unavailable. Capture or index knowledge before searching.

What it means

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.

Source

Thrown at packages/memory/src/processors/observational-memory/subconscious/semantic-index.ts:77

    const draining = this.#drain(scope).finally(() => {
      this.#draining.delete(key);
    });
    this.#draining.set(key, draining);
    return draining;
  }

  async search(query: string, scope: KnowledgeScope, limit = 10) {
    await this.drain(scope);
    const result = await this.#embedder.doEmbed({
      values: [query],
      ...(this.#embedderOptions ?? {}),
    } as never);
    const embedding = result.embeddings[0];
    if (!embedding?.length) throw new Error('Embedder returned no vector for knowledge search query.');

    const indexName = this.#indexName(embedding.length);
    if (!(await this.#knowledgeIndexes()).includes(indexName)) {
      throw new StaleKnowledgeSemanticIndexError(
        `Knowledge semantic index ${indexName} is unavailable. Capture or index knowledge before searching.`,
      );
    }

    const visibleScopeKeys = scope.map((_, index) => scope.slice(0, index + 1).join('\u001f'));
    const batches = await Promise.all(
      visibleScopeKeys.map(scopeKey =>
        this.#vector.query({
          indexName,
          queryVector: embedding,
          topK: limit,
          filter: { scope_key: scopeKey },
        }),
      ),
    );
    const deduped = new Map<string, (typeof batches)[number][number]>();
    for (const candidate of batches.flat()) {
      const candidateScope = candidate.metadata?.scope;

View on GitHub (pinned to 75dd419e61)

Solutions

1. Capture/index knowledge first (run the observation/indexing pipeline) so the semantic index for your embedder's dimension is created.
2. Re-index existing documents after changing the embedding model/dimension, or revert to the original embedder.
3. Confirm you are connected to the intended storage environment that already contains the knowledge index.

Example fix

// before (searching a fresh DB)
await remind(context); // StaleKnowledgeSemanticIndexError
// after — index first
await semanticIndexer.capture(documents);
await semanticIndexer.search(scope, query);

const store = await memory.storage.getStore('knowledge');
const indexes = await store.listVectorIndexes?.() ?? [];
// if your embedder dimension is 1536, an index for that dimension must exist before searching
if (!indexes.some((n) => n.includes('1536'))) console.warn('knowledge semantic index missing — capture/index knowledge first');

function indexExistsForDimension(indexNames, dimension) {
  return indexNames.includes(`knowledge_${dimension}`); // adjust to your #indexName convention
}

try {
  return await remind(context);
} catch (e) {
  if (e instanceof StaleKnowledgeSemanticIndexError && e.message.includes('is unavailable')) {
    logger.info('no knowledge indexed yet for this scope; skipping remind');
    return;
  }
  throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Invalid model string format: "${config}". Expected format: "
• Vector configuration is required to embed text.
• Batch embedder returned no embedding for input text.
• Tokenizer file not found at ${tokenizerPath}
• Config file not found at ${configPath}

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