mastra-ai/mastra · error

Embedding dimension must be ${this.dimension}

Error message

Embedding dimension must be ${this.dimension}

What it means

GraphRAG is initialized with a vector dimension, and addNode enforces that every node's embedding length equals this.dimension. Mismatched dimensions make cosine-similarity computations undefined/incorrect, so the graph rejects the node. Usually indicates mixing embedding models of different output sizes (e.g. 1536 vs 3072 vs 768).

Source

Thrown at packages/rag/src/graph-rag/index.ts:72

  private nodes: Map<string, GraphNode>;
  private edges: GraphEdge[];
  private dimension: number;
  private threshold: number;

  constructor(dimension: number = 1536, threshold: number = 0.7) {
    this.nodes = new Map();
    this.edges = [];
    this.dimension = dimension;
    this.threshold = threshold;
  }

  // Add a node to the graph
  addNode(node: GraphNode): void {
    if (!node.embedding) {
      throw new Error('Node must have an embedding');
    }
    if (node.embedding.length !== this.dimension) {
      throw new Error(`Embedding dimension must be ${this.dimension}`);
    }
    this.nodes.set(node.id, node);
  }

  // Add an edge between two nodes
  addEdge(edge: GraphEdge): void {
    if (!this.nodes.has(edge.source) || !this.nodes.has(edge.target)) {
      throw new Error('Both source and target nodes must exist');
    }
    this.edges.push(edge);
    // Add reverse edge
    this.edges.push({
      source: edge.target,
      target: edge.source,
      weight: edge.weight,
      type: edge.type,
    });
  }

View on GitHub (pinned to 75dd419e61)

Solutions

1. Re-embed all documents with the same model used for the graph/query embeddings.
2. Construct GraphRAG with the dimension matching your embedding model, or omit dimension to infer it from the first node.
3. Verify the embedding model's output dimension (e.g. via a test embed) and use it consistently everywhere.
4. If migrating models, re-embed the whole corpus — never mix dimensions in one graph.

Example fix

// before
const graph = new GraphRAG({ dimension: 1536 });
graph.addNode({ id, content, embedding: largeModelEmbedding }); // 3072-dim
// after
const graph = new GraphRAG({ dimension: embeddings[0].length });
graph.addNode({ id, content, embedding: embeddings[0] });

const dim = embeddings[0].length;
const bad = nodes.filter(n => n.embedding!.length !== dim);
if (bad.length) throw new Error(`Dimension mismatch: expected ${dim}, got ${bad.map(n => n.embedding!.length).join(',')}`);

try {
  nodes.forEach(n => graph.addNode(n));
} catch (e) {
  if ((e as Error).message.startsWith('Embedding dimension must be')) {
    console.error('Mixed embedding models detected; re-embed the corpus with one model');
  }
  throw e;
}

When it happens

Trigger: addNode/createGraph with embeddings from a different model than the one used to create the GraphRAG instance, e.g. graph created with dimension 1536 (text-embedding-3-small) but nodes embedded with text-embedding-3-large (3072) or a local 768-dim model.

Common situations: Switching embedding models mid-pipeline without re-embedding the corpus; storing embeddings from different providers in one collection; a provider silently changing default dimensions; reusing a cached GraphRAG instance configured for an older model.

Related errors

• Node must have an embedding
• Vector dimensions must match: vec1(${vec1.length}) !== vec2(
• Query embedding must have dimension ${this.dimension}
• Both source and target nodes must exist
• Vectors must not be null or undefined

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