gastownhall/beads · error

node %q: metadata ref %q references unknown key %q

Error message

node %q: metadata ref %q references unknown key %q

What it means

A node's `metadata_refs` map values must reference keys of other nodes in the same plan. Validation looks the referenced key up in the seen-keys set (and falls back to scanning plan nodes) and errors if the target key is unknown.

Source

Thrown at cmd/bd/graph_apply.go:562

		}
		if node.ID != "" {
			if seenIDs[node.ID] {
				return fmt.Errorf("duplicate explicit id %q (node %q)", node.ID, node.Key)
			}
			seenIDs[node.ID] = true
		}
		// Validate MetadataRefs point to known keys.
		for metaKey, refKey := range node.MetadataRefs {
			if !seenKeys[refKey] {
				found := false
				for _, other := range plan.Nodes {
					if other.Key == refKey {
						found = true
						break
					}
				}
				if !found {
					return fmt.Errorf("node %q: metadata ref %q references unknown key %q", node.Key, metaKey, refKey)
				}
			}
		}
		parentKey := node.effectiveParentKey()
		if parentKey != "" && !seenKeys[parentKey] {
			found := false
			for _, other := range plan.Nodes {
				if other.Key == parentKey {
					found = true
					break
				}
			}
			if !found {
				return fmt.Errorf("node %q: parent key %q not found in plan", node.Key, parentKey)
			}
		}
		for j, dep := range node.Deps {
			if dep.Target == "" {

View on GitHub (pinned to 71377f2769)

Solutions

1. Correct the metadata ref value to match an existing node key in the plan
2. Add the missing node to plan.nodes if it should exist
3. Remove the metadata ref if it is no longer needed

Example fix

// before
{"key": "deploy", "metadata_refs": {"blocked_by": "db-migrte"}}
// after
{"key": "deploy", "metadata_refs": {"blocked_by": "db-migrate"}}

keys := map[string]bool{}
for _, n := range plan.Nodes { keys[n.Key] = true }
for _, n := range plan.Nodes {
	for mk, ref := range n.MetadataRefs {
		if !keys[ref] { return fmt.Errorf("node %s: meta ref %s -> unknown key %s", n.Key, mk, ref) }
	}
}

if err := bd.GraphApply(ctx, plan, opts); err != nil {
	if strings.Contains(err.Error(), "references unknown key") {
		// repair the metadata ref and retry
	}
}

When it happens

Trigger: `bd graph apply` where node X has metadata_refs[metaKey] = "some-key" but no node with key "some-key" exists in the plan.

Common situations: Typos in referenced keys; referencing nodes that were deleted from the plan; referencing nodes expected to exist in the tracker instead of the plan (refs must be in-plan).

Related errors

• node %q: parent key %q not found in plan
• edge %d: from key %q not found in plan
• edge %d: to key %q not found in plan
• duplicate node key %q
• node %q has empty title

AI-assisted analysis of gastownhall/beads@71377f2769 (2026-08-30). Data as JSON: /api/errors/694067f8b0278124. Report an issue: GitHub.