mastra-ai/mastra · error

Edge references unknown node: ${edge.target}

Error message

Edge references unknown node: ${edge.target}

What it means

Same integrity check as the source-side one: deserialize() also verifies that edge.target exists among the restored nodes before assigning the edge list. A snapshot with an edge pointing at a nonexistent target is rejected because queries and random walks would traverse to missing nodes.

Source

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

    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 = [];
  }

  updateNodeContent(id: string, newContent: string): void {
    const node = this.nodes.get(id);
    if (!node) {

View on GitHub (pinned to 75dd419e61)

Solutions

  1. Filter or repair edges whose target is missing from snapshot.nodes before deserializing.
  2. Regenerate the snapshot via serialize() from a consistent in-memory graph.
  3. Apply id migrations to both nodes and edges together.
  4. Run a referential-integrity check (Set of node ids) on snapshots before loading them.

Example fix

// before
const graph = GraphRAG.deserialize(savedSnapshot);
// after
const ids = new Set(savedSnapshot.nodes.map(n => n.id));
for (const e of savedSnapshot.edges) {
  if (!ids.has(e.target)) throw new Error(`snapshot corrupt: edge target ${e.target} missing`);
}
const graph = GraphRAG.deserialize(savedSnapshot);
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.target));
if (dangling.length) throw new Error(`Edges with unknown target: ${dangling.map(e => e.target).join(',')}`);

Type guard

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

Try / catch

try {
  const graph = GraphRAG.deserialize(snapshot);
} catch (e) {
  if ((e as Error).message.startsWith('Edge references unknown node')) {
    snapshot.edges = snapshot.edges.filter(e =>
      snapshot.nodes.some(n => n.id === e.target));
    // retry deserialize
  } else throw e;
}

Prevention

When it happens

Trigger: GraphRAG.deserialize(snapshot) with an edge whose target id is absent from snapshot.nodes — typically from hand-edited/pruned snapshots, id remapping, or a snapshot merged from incompatible graphs.

Common situations: Deleting a node's entry in persisted JSON while keeping its edges; exporting edges but a subset of nodes; id scheme changes (e.g. numeric to hash ids) applied only to nodes.

Related errors

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