{"record":{"id":"cf4a5c4a240fe649","repo":"mastra-ai/mastra","slug":"unsupported-graphrag-snapshot-version-snapshot","errorCode":null,"errorMessage":"Unsupported GraphRAG snapshot version: ${snapshot?.version}","messagePattern":"Unsupported GraphRAG snapshot version: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"packages/rag/src/graph-rag/index.ts","lineNumber":137,"sourceCode":"      threshold: this.threshold,\n      nodes: Array.from(this.nodes.values()).map(node => ({\n        ...node,\n        ...(node.embedding ? { embedding: [...node.embedding] } : {}),\n        ...(node.metadata ? { metadata: structuredClone(node.metadata) } : {}),\n      })),\n      edges: this.edges.map(edge => ({ ...edge })),\n    };\n  }\n\n  /**\n   * Rebuild a GraphRAG instance from a snapshot produced by `serialize()`.\n   *\n   * @throws if the snapshot version is unsupported, a node embedding does not\n   * match the snapshot dimension, or an edge references an unknown node.\n   */\n  static deserialize(snapshot: GraphRAGSnapshot): GraphRAG {\n    if (snapshot?.version !== GRAPH_RAG_SNAPSHOT_VERSION) {\n      throw new Error(`Unsupported GraphRAG snapshot version: ${snapshot?.version}`);\n    }\n\n    const graph = new GraphRAG(snapshot.dimension, snapshot.threshold);\n\n    for (const node of snapshot.nodes ?? []) {\n      // Route through addNode so embedding presence and dimension are validated\n      // at load time rather than failing later inside query().\n      graph.addNode({\n        ...node,\n        ...(node.embedding ? { embedding: [...node.embedding] } : {}),\n        ...(node.metadata ? { metadata: structuredClone(node.metadata) } : {}),\n      });\n    }\n\n    for (const edge of snapshot.edges ?? []) {\n      if (!graph.nodes.has(edge.source)) {\n        throw new Error(`Edge references unknown node: ${edge.source}`);\n      }","sourceCodeStart":119,"sourceCodeEnd":155,"githubUrl":"https://github.com/mastra-ai/mastra/blob/75dd419e613fe9c39f846ffc500716141b74fda6/packages/rag/src/graph-rag/index.ts#L119-L155","documentation":"GraphRAG.serialize() stamps a snapshot format version (currently 1). deserialize() rejects any snapshot whose version field differs from GRAPH_RAG_SNAPSHOT_VERSION, or that is null/undefined, because the node/edge shape cannot be assumed compatible across versions. This guards against loading stale or hand-built snapshots.","triggerScenarios":"Calling GraphRAG.deserialize(snapshot) with snapshot===null/undefined, with a snapshot object missing the version field, with a hand-constructed object literal lacking version, or with a snapshot produced by a different (future/older) library version.","commonSituations":"Persisted snapshots from an older mastra release being loaded after an upgrade; manually crafting a GraphRAGSnapshot literal and forgetting version; JSON.parse of a file that is not actually a snapshot; deserializing data fetched from the wrong storage key.","solutions":["Verify the snapshot came from GraphRAG.serialize() of a matching library version; re-serialize the graph with the current version if possible.","If loading a legacy snapshot, add a migration step that sets version to 1 after converting the old shape.","Check that the persisted blob was not truncated or overwritten — null/undefined snapshot means the load itself failed.","Add a pre-call guard that checks snapshot?.version === 1 before calling deserialize."],"exampleFix":"// before\nconst graph = GraphRAG.deserialize(JSON.parse(raw));\n// after\nconst snapshot = JSON.parse(raw);\nif (snapshot?.version !== 1) {\n  throw new Error(`Snapshot file version ${snapshot?.version} unsupported; rebuild the index`);\n}\nconst graph = GraphRAG.deserialize(snapshot);","handlingStrategy":"validation","validationCode":"function isValidSnapshot(s: unknown): s is GraphRAGSnapshot {\n  return !!s && typeof s === 'object' && (s as any).version === 1\n    && Array.isArray((s as any).nodes) && Array.isArray((s as any).edges);\n}","typeGuard":"const isGraphRAGSnapshot = (v: unknown): v is GraphRAGSnapshot =>\n  typeof v === 'object' && v !== null && (v as GraphRAGSnapshot).version === 1;","tryCatchPattern":"try {\n  const graph = GraphRAG.deserialize(snapshot);\n} catch (e) {\n  if ((e as Error).message.startsWith('Unsupported GraphRAG snapshot version')) {\n    // rebuild index via createGraph or migrate the snapshot\n  } else throw e;\n}","preventionTips":["Only pass snapshots produced by GraphRAG.serialize()","Store the library version alongside the persisted snapshot","Version-check snapshots right after JSON.parse, before deserialize","Never hand-write GraphRAGSnapshot literals"],"tags":["serialization","version-mismatch","rag","validation"],"backgroundTag":"incompatible-data-version","analyzedSha":"75dd419e613fe9c39f846ffc500716141b74fda6","analyzedAt":"2026-08-30T00:15:31.844Z","schemaVersion":2},"datasetVersion":"2026-08-30T03:17:51.788Z"}