mastra-ai/mastra · error

Edge references unknown node: ${edge.source}

Error message

Edge references unknown node: ${edge.source}

What it means

During deserialize(), every snapshot edge must reference nodes that exist in the snapshot's node list. If edge.source is not found among the restored nodes, the graph would be internally inconsistent, so deserialize throws. This protects against corrupted or hand-edited snapshots.

Source

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

    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}`);
      }
      if (!graph.nodes.has(edge.target)) {
        throw new Error(`Edge references unknown node: ${edge.target}`);
      }
    }

    // Assign directly rather than via addEdge: the serialized edge list already
    // contains both directions, and addEdge would add the reverse edge again.
    graph.edges = (snapshot.edges ?? []).map(edge => ({ ...edge }));

    return graph;
  }

  clear(): void {
    this.nodes.clear();
    this.edges = [];
  }

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Ensure every edge's source/target exists in snapshot.nodes; filter out dangling edges before deserializing.
  2. Rebuild the snapshot from the live graph with serialize() instead of hand-editing persisted JSON.
  3. If node ids were remapped, remap edge source/target ids in the same migration.
  4. Validate the snapshot offline: build a Set of node ids and drop edges not present in it.

Example fix

// before
const graph = GraphRAG.deserialize(snapshot);
// after
const ids = new Set(snapshot.nodes.map(n => n.id));
snapshot.edges = snapshot.edges.filter(e => ids.has(e.source) && ids.has(e.target));
const graph = GraphRAG.deserialize(snapshot);
Defensive patterns

Strategy: validation

Validate before calling

const ids = new Set(snapshot.nodes.map(n => n.id));
const dangling = snapshot.edges.filter(e => !ids.has(e.source));
if (dangling.length) throw new Error(`Edges with unknown source: ${dangling.map(e => e.source).join(',')}`);

Type guard

const edgesHaveKnownSources = (s: GraphRAGSnapshot): boolean => {
  const ids = new Set(s.nodes.map(n => n.id));
  return s.edges.every(e => ids.has(e.source));
};

Try / catch

try {
  const graph = GraphRAG.deserialize(snapshot);
} catch (e) {
  if ((e as Error).message.startsWith('Edge references unknown node')) {
    // sanitize snapshot: drop dangling edges, then retry
  } else throw e;
}

Prevention

When it happens

Trigger: Calling GraphRAG.deserialize(snapshot) where snapshot.edges contains an edge whose source id is not present in snapshot.nodes — e.g. nodes were filtered out, ids were renamed, or the edges array was hand-written.

Common situations: Manually pruning nodes from a serialized snapshot without pruning dependent edges; changing node id schemes between exports; merging snapshots from two graphs with different id spaces; partially truncated JSON that lost node entries but kept edges.

Related errors

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