mastra-ai/mastra · error

Vector configuration is required to embed text.

Error message

Vector configuration is required to embed text.

What it means

An embedding was requested (directly or as part of vector indexing/querying) but the engine has no `vectorConfig`, so there is no embedder to convert text into vectors. The private `#embedOne` guard throws before touching any embedder. It surfaces from `embedding`/`queryEmbedding` paths.

Source

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

      return 'hybrid';
    }
    if (this.canVector) {
      return 'vector';
    }
    if (this.canBM25) {
      return 'bm25';
    }

    throw new Error('No search configuration available. Provide bm25 or vector config.');
  }

  /**
   * Embed a single text, dispatching to the batch path with a one-element array
   * when the configured embedder is batch-capable.
   */
  async #embedOne(text: string): Promise<number[]> {
    if (!this.#vectorConfig) {
      throw new Error('Vector configuration is required to embed text.');
    }
    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[][]> {

View on GitHub (pinned to 75dd419e61)

Solutions

1. Supply a `vectorConfig` with a working embedder, vector store, and indexName when constructing the SearchEngine.
2. Skip embedding operations when `engine.canVector` is false (use BM25 search instead).
3. Check that the vector/embedding provider configuration (API keys, model) is present in the environment before engine construction.

Example fix

// before
const engine = new SearchEngine({ bm25: {} });
await engine.queryEmbedding('query'); // throws

// after
const engine = new SearchEngine({
  bm25: {},
  vectorConfig: { vectorStore, embedder, indexName: 'docs' },
});
await engine.queryEmbedding('query');

if (!engine.canVector) {
  throw new Error('Embedding requires vector configuration (embedder + vector store).');
}
const vec = await engine.queryEmbedding(text);

When it happens

Trigger: Calling embedding-dependent operations such as `queryEmbedding(text)` or indexing with vector output on a SearchEngine constructed without `vectorConfig` (no vectorStore/embedder/indexName).

Common situations: BM25-only deployments whose indexing path unconditionally triggers vector embedding; env-based wiring where the embedding provider config failed to load; calling low-level vector APIs (embed/queryEmbedding) instead of search on a keyword-only engine.

Related errors

• Invalid model string format: "${config}". Expected format: "
• BM25 search requires BM25 configuration.
• Hybrid search requires both vector and BM25 configuration.
• No search configuration available. Provide bm25 or vector co
• Batch embedder returned no embedding for input text.

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