Unsupported GraphRAG snapshot version: ${snapshot?.version}

Error message

Unsupported GraphRAG snapshot version: ${snapshot?.version}

What it means

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.

Source

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

      threshold: this.threshold,
      nodes: Array.from(this.nodes.values()).map(node => ({
        ...node,
        ...(node.embedding ? { embedding: [...node.embedding] } : {}),
        ...(node.metadata ? { metadata: structuredClone(node.metadata) } : {}),
      })),
      edges: this.edges.map(edge => ({ ...edge })),
    };
  }

  /**
   * Rebuild a GraphRAG instance from a snapshot produced by `serialize()`.
   *
   * @throws if the snapshot version is unsupported, a node embedding does not
   * match the snapshot dimension, or an edge references an unknown node.
   */
  static deserialize(snapshot: GraphRAGSnapshot): GraphRAG {
    if (snapshot?.version !== GRAPH_RAG_SNAPSHOT_VERSION) {
      throw new Error(`Unsupported GraphRAG snapshot version: ${snapshot?.version}`);
    }

    const graph = new GraphRAG(snapshot.dimension, snapshot.threshold);

    for (const node of snapshot.nodes ?? []) {
      // Route through addNode so embedding presence and dimension are validated
      // at load time rather than failing later inside query().
      graph.addNode({
        ...node,
        ...(node.embedding ? { embedding: [...node.embedding] } : {}),
        ...(node.metadata ? { metadata: structuredClone(node.metadata) } : {}),
      });
    }

    for (const edge of snapshot.edges ?? []) {
      if (!graph.nodes.has(edge.source)) {
        throw new Error(`Edge references unknown node: ${edge.source}`);
      }

View on GitHub (pinned to 75dd419e61)

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.

Example fix

// before
const graph = GraphRAG.deserialize(JSON.parse(raw));
// after
const snapshot = JSON.parse(raw);
if (snapshot?.version !== 1) {
  throw new Error(`Snapshot file version ${snapshot?.version} unsupported; rebuild the index`);
}
const graph = GraphRAG.deserialize(snapshot);

Defensive patterns

Strategy: validation

Validate before calling

function isValidSnapshot(s: unknown): s is GraphRAGSnapshot {
  return !!s && typeof s === 'object' && (s as any).version === 1
    && Array.isArray((s as any).nodes) && Array.isArray((s as any).edges);
}

Type guard

const isGraphRAGSnapshot = (v: unknown): v is GraphRAGSnapshot =>
  typeof v === 'object' && v !== null && (v as GraphRAGSnapshot).version === 1;

Try / catch

try {
  const graph = GraphRAG.deserialize(snapshot);
} catch (e) {
  if ((e as Error).message.startsWith('Unsupported GraphRAG snapshot version')) {
    // rebuild index via createGraph or migrate the snapshot
  } else throw e;
}

Prevention

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

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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