mastra-ai/mastra · error

Vector configuration is required to embed texts.

Error message

Vector configuration is required to embed texts.

What it means

SearchEngine throws this when #embedAll is called but the engine was constructed without vector configuration (this.#vectorConfig is null/undefined). Embedding is only supported when a vectorConfig containing an embedder (and vectorStore) was supplied, since embeddings have no meaning without a target vector store. It is an internal invariant guard surfaced through the public embeddings path.

Source

Thrown at packages/core/src/workspace/search/search-engine.ts:701

    const { embedder } = this.#vectorConfig;
    if (isBatchEmbedder(embedder)) {
      const [embedding] = await embedder([text]);
      if (!embedding) {
        throw new Error('Batch embedder returned no embedding for input text.');
      }
      return embedding;
    }
    return embedder(text);
  }

  /**
   * Embed many texts. Uses a single batched call (chunked by `maxBatchSize`)
   * when the embedder is batch-capable; otherwise falls back to parallel
   * single-text calls.
   */
  async #embedAll(texts: string[]): Promise<number[][]> {
    if (!this.#vectorConfig) {
      throw new Error('Vector configuration is required to embed texts.');
    }
    if (texts.length === 0) return [];

    const { embedder } = this.#vectorConfig;

    if (isBatchEmbedder(embedder)) {
      // Same sanitized size the callers group by, so an unusable `maxBatchSize` can never turn
      // this loop into a non-advancing one.
      const max = resolveEmbedGroupSize(embedder);
      if (texts.length <= max) {
        return embedder(texts);
      }
      // Chunk by maxBatchSize and run chunks in parallel up to DEFAULT_INDEX_MANY_CONCURRENCY.
      const results = await pMap(chunkItems(texts, max), chunk => embedder(chunk), {
        concurrency: DEFAULT_INDEX_MANY_CONCURRENCY,
      });
      return results.flat();
    }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Provide a `vector` configuration (with `embedder`, `vectorStore`, `indexName`) when constructing the SearchEngine if you intend to embed texts.
2. Verify your config-loading code actually resolves the vector settings (check env vars/flags) and that the object is spread without dropping the `vector` key.
3. If you only need keyword search, avoid calling embedding-dependent methods and construct/use the BM25-only path instead.

Example fix

// before
const engine = new SearchEngine({ bm25: bm25Config });
await engine.upsert(docs); // throws: no vector config
// after
const engine = new SearchEngine({
  bm25: bm25Config,
  vector: { embedder: new FastEmbed(), vectorStore: store, indexName: 'docs' },
});
await engine.upsert(docs);

function hasVectorConfig(engineOpts) {
  return Boolean(engineOpts?.vector?.embedder && engineOpts?.vector?.vectorStore);
}
if (!hasVectorConfig(opts)) throw new Error('SearchEngine requires vector config before embedding.');
const engine = new SearchEngine(opts);

function hasVectorConfig(o) {
  return typeof o === 'object' && o !== null && 'vector' in o &&
    typeof o.vector === 'object' && o.vector !== null &&
    'embedder' in o.vector && 'vectorStore' in o.vector;
}

try {
  await engine.upsert(docs);
} catch (err) {
  if (err instanceof Error && err.message.includes('Vector configuration is required')) {
    engine = new SearchEngine({ ...opts, vector: vectorConfig });
    await engine.upsert(docs);
  } else throw err;
}

When it happens

Trigger: Calling any embedding-dependent flow (e.g. upsert/index of documents via embeddings -> #embedAll) on a SearchEngine constructed without a `vector` config; passing options that omit `vector.embedder`; constructing SearchEngine for BM25-only use and then invoking an embedding code path.

Common situations: Developers build a keyword-only search engine and later try to index documents into it; a config object is conditionally spread so the `vector` key is dropped; env-driven config loading fails silently and passes undefined; refactors rename the config field so the engine no longer picks it up.

Related errors

• SEMANTIC_RECALL_MISSING_VECTOR_ADAPTER
• Vector search requires vector configuration.
• Vector store ${vectorName} not found
• AcpAgent does not support resuming suspended generate calls
• ACP prompt stopped before completing: ${response.stopReason}

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