{"record":{"id":"022ac40a39f08617","repo":"mastra-ai/mastra","slug":"node-must-have-an-embedding","errorCode":null,"errorMessage":"Node must have an embedding","messagePattern":"Node must have an embedding","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/rag/src/graph-rag/index.ts","lineNumber":69,"sourceCode":"const GRAPH_RAG_SNAPSHOT_VERSION = 1;\n\nexport class GraphRAG {\n  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,","sourceCodeStart":51,"sourceCodeEnd":87,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/rag/src/graph-rag/index.ts#L51-L87","documentation":"GraphRAG's addNode requires every node to carry an embedding vector, since similarity edges and graph traversal are computed from embeddings. If node.embedding is falsy (undefined/null/empty), the node cannot participate and the method throws. It is a structural precondition of building the graph.","triggerScenarios":"Calling graph.addNode(node) or createGraph({ nodes }) where some nodes were constructed without an embedding field, or where embedding generation (embedMany/upsert step) silently failed or was skipped.","commonSituations":"Mixing documents that were embedded with raw records loaded from a database; a failed embed() step returning partial results; hand-building GraphNode objects for tests without embeddings; deserializing old/partial data (though deserialize filters).","solutions":["Embed all documents first with embedMany (or via MDocument.embed) and attach results: { ...doc, embedding: embeddings[i] }.","Filter out nodes lacking embeddings before calling addNode/createGraph.","Check your embedding step for silent failures (empty response arrays, rate-limit partials).","If a node legitimately has no embedding, exclude it from the graph rather than passing null."],"exampleFix":"// before\nnodes.forEach(n => graph.addNode({ id: n.id, content: n.text }));\n// after\nconst { embeddings } = await embedMany({ model, values: nodes.map(n => n.text) });\nnodes.forEach((n, i) => graph.addNode({ id: n.id, content: n.text, embedding: embeddings[i] }));","handlingStrategy":"validation","validationCode":"function assertEmbeddings(nodes: { id: string; embedding?: number[] }[]): void {\n  const missing = nodes.filter(n => !n.embedding || n.embedding.length === 0);\n  if (missing.length) throw new Error(`Nodes missing embeddings: ${missing.map(n => n.id).join(', ')}`);\n}","typeGuard":"function hasEmbedding(n: GraphNode): n is GraphNode & { embedding: number[] } {\n  return Array.isArray(n.embedding) && n.embedding.length > 0;\n}","tryCatchPattern":"try {\n  nodes.forEach(n => graph.addNode(n));\n} catch (e) {\n  if ((e as Error).message === 'Node must have an embedding') {\n    console.error('A node reached addNode without an embedding; re-run the embed step');\n  }\n  throw e;\n}","preventionTips":["Always run embedMany/upsert and attach embeddings before building the graph.","Filter nodes with !embedding before createGraph.","Assert embedding presence in your ingestion pipeline tests.","Check embed results for empty/partial arrays after API calls."],"tags":["rag","graph-rag","embedding","validation"],"backgroundTag":"missing-embedding-vector","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}