{"record":{"id":"121ac8afa7e92643","repo":"mastra-ai/mastra","slug":"embedding-dimension-must-be-this-dimension","errorCode":null,"errorMessage":"Embedding dimension must be ${this.dimension}","messagePattern":"Embedding dimension must be (.+?)","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/rag/src/graph-rag/index.ts","lineNumber":72,"sourceCode":"  private nodes: Map<string, GraphNode>;\n  private edges: GraphEdge[];\n  private dimension: number;\n  private threshold: number;\n\n  constructor(dimension: number = 1536, threshold: number = 0.7) {\n    this.nodes = new Map();\n    this.edges = [];\n    this.dimension = dimension;\n    this.threshold = threshold;\n  }\n\n  // Add a node to the graph\n  addNode(node: GraphNode): void {\n    if (!node.embedding) {\n      throw new Error('Node must have an embedding');\n    }\n    if (node.embedding.length !== this.dimension) {\n      throw new Error(`Embedding dimension must be ${this.dimension}`);\n    }\n    this.nodes.set(node.id, node);\n  }\n\n  // Add an edge between two nodes\n  addEdge(edge: GraphEdge): void {\n    if (!this.nodes.has(edge.source) || !this.nodes.has(edge.target)) {\n      throw new Error('Both source and target nodes must exist');\n    }\n    this.edges.push(edge);\n    // Add reverse edge\n    this.edges.push({\n      source: edge.target,\n      target: edge.source,\n      weight: edge.weight,\n      type: edge.type,\n    });\n  }","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/rag/src/graph-rag/index.ts#L54-L90","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-embed all documents with the same model used for the graph/query embeddings.","Construct GraphRAG with the dimension matching your embedding model, or omit dimension to infer it from the first node.","Verify the embedding model's output dimension (e.g. via a test embed) and use it consistently everywhere.","If migrating models, re-embed the whole corpus — never mix dimensions in one graph."],"exampleFix":"// before\nconst graph = new GraphRAG({ dimension: 1536 });\ngraph.addNode({ id, content, embedding: largeModelEmbedding }); // 3072-dim\n// after\nconst graph = new GraphRAG({ dimension: embeddings[0].length });\ngraph.addNode({ id, content, embedding: embeddings[0] });","handlingStrategy":"validation","validationCode":"const dim = embeddings[0].length;\nconst bad = nodes.filter(n => n.embedding!.length !== dim);\nif (bad.length) throw new Error(`Dimension mismatch: expected ${dim}, got ${bad.map(n => n.embedding!.length).join(',')}`);","typeGuard":null,"tryCatchPattern":"try {\n  nodes.forEach(n => graph.addNode(n));\n} catch (e) {\n  if ((e as Error).message.startsWith('Embedding dimension must be')) {\n    console.error('Mixed embedding models detected; re-embed the corpus with one model');\n  }\n  throw e;\n}","preventionTips":["Use one embedding model for the entire corpus and all queries.","Verify the model's output dimension once and store it with your config.","Re-embed everything when switching models; never mix vectors of different lengths.","Omit `dimension` in GraphRAG options to infer it from data, or set it from the actual model."],"tags":["rag","graph-rag","embedding","dimension-mismatch"],"backgroundTag":"embedding-dimension-mismatch","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T08:17:16.595Z"}