mastra-ai/mastra · error · MastraError

MASTRA_MEMORY_GET_EMBEDDING_DIMENSION_FAILED

MASTRA_MEMORY_GET_EMBEDDING_DIMENSION_FAILED

Error message

Failed to determine the embedder's output dimension. Semantic recall cannot safely select a vector index until the embedder returns a usable embedding. Check that the embedder is reachable and correctly configured.

What it means

This MastraError wraps any failure in getEmbeddingDimension, including the empty-probe error (1422) and network/auth errors from the embedder. It signals that the embedder's output dimension could not be determined, so semantic recall cannot safely pick or create a correctly-sized vector index. Domain is MASTRA_VECTOR, category THIRD_PARTY.

Source

Thrown at packages/core/src/memory/memory.ts:312

   * Probe the embedder to determine its actual output dimension.
   * The result is cached so subsequent calls are free.
   */
  protected async getEmbeddingDimension(): Promise<number | undefined> {
    if (!this.embedder) return undefined;
    if (!this._embeddingDimensionPromise) {
      this._embeddingDimensionPromise = (async () => {
        try {
          const result = await this.embedder!.doEmbed({
            values: ['a'],
            ...(this.embedderOptions || {}),
          } as any);
          const dimension = result.embeddings[0]?.length;
          if (!dimension) {
            throw new Error('Embedder returned no usable embedding for the dimension probe.');
          }
          return dimension;
        } catch (e) {
          throw new MastraError(
            {
              id: 'MASTRA_MEMORY_GET_EMBEDDING_DIMENSION_FAILED',
              domain: ErrorDomain.MASTRA_VECTOR,
              category: 'THIRD_PARTY',
              text:
                `Failed to determine the embedder's output dimension. Semantic recall cannot safely select a ` +
                `vector index until the embedder returns a usable embedding. Check that the embedder is reachable ` +
                `and correctly configured.`,
            },
            e,
          );
        }
      })();
    }
    return this._embeddingDimensionPromise;
  }

  /**

View on GitHub (pinned to 75dd419e61)

Solutions

1. Verify the embedder is reachable: check network, API keys, and model identifiers in embedderOptions.
2. Call the embedder's doEmbed directly with values: ['a'] to reproduce and inspect the underlying error.
3. Ensure doEmbed returns { embeddings: [[...]] } with a non-empty vector.
4. Catch and inspect e.cause / the wrapped original error for the root cause.

Example fix

// before
const dim = await memory.embeddingDimension(); // throws MASTRA_MEMORY_GET_EMBEDDING_DIMENSION_FAILED

// after
try {
  const dim = await memory.embeddingDimension();
} catch (e) {
  console.error('Embedder probe failed:', (e as any).cause ?? e);
}

try { await embedder.doEmbed({ values: ['a'] }); } catch (e) { /* fix reachability/keys before calling memory.embeddingDimension() */ }

try {
  const dim = await memory.embeddingDimension();
} catch (e) {
  if ((e as any).id === 'MASTRA_MEMORY_GET_EMBEDDING_DIMENSION_FAILED') {
    console.error('Embedder probe failed (network/keys/model):', (e as any).cause ?? e);
  } else throw e;
}

When it happens

Trigger: Any call path to getEmbeddingDimension (via embeddingDimension / createEmbeddingIndex) where doEmbed throws (network failure, bad API key, model unavailable) or returns no usable embedding.

Common situations: Embedder provider unreachable (offline dev, DNS/proxy issues); invalid or expired API keys; wrong model name in embedder options; test stubs returning empty embeddings; rate limits on the embedding API.

Related errors

• Embedder returned no usable embedding for the dimension prob
• SEMANTIC_RECALL_MISSING_EMBEDDER
• Tried to embed message content but this Memory instance does
• Gateway API error ${res.status}: ${body}
• Token exchange failed: ${error}

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