gastownhall/beads · error

node %q: parent key %q not found in plan

Error message

node %q: parent key %q not found in plan

What it means

A node's effective parent key (from parent_key or hierarchy hints) must correspond to a node in the plan. If the parent key is set but not found among plan nodes, validation fails because hierarchical structure cannot be resolved.

Source

Thrown at cmd/bd/graph_apply.go:576

						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 == "" {
				return fmt.Errorf("node %q: dep %d has empty target", node.Key, j)
			}
			if dep.Type != "" {
				dt := types.DependencyType(dep.Type)
				if !dt.IsValid() {
					return fmt.Errorf("node %q: dep %d: invalid dependency type %q", node.Key, j, dep.Type)
				}
			}
		}
	}

	for i, edge := range plan.Edges {
		if edge.FromKey != "" && !seenKeys[edge.FromKey] {
			return fmt.Errorf("edge %d: from key %q not found in plan", i, edge.FromKey)

View on GitHub (pinned to 71377f2769)

Solutions

1. Fix the parent_key spelling to match a node key in the plan
2. Add the parent node to plan.nodes
3. Remove or blank the parent_key if the node should be a root

Example fix

// before
{"key": "child", "parent_key": "parnet"}
// after
{"key": "child", "parent_key": "parent"}

keys := map[string]bool{}
for _, n := range plan.Nodes { keys[n.Key] = true }
for _, n := range plan.Nodes {
	if p := n.EffectiveParentKey(); p != "" && !keys[p] { return fmt.Errorf("node %s: parent %s missing", n.Key, p) }
}

if err := bd.GraphApply(ctx, plan, opts); err != nil {
	if strings.Contains(err.Error(), "parent key") && strings.Contains(err.Error(), "not found in plan") {
		// fix or drop parent_key and retry
	}
}

When it happens

Trigger: `bd graph apply` with a node whose parent_key names a key absent from plan.nodes.

Common situations: Typos in parent_key; deleting or renaming a parent node without updating children; expecting the parent to come from the existing tracker rather than the plan.

Related errors

• node %q: metadata ref %q references unknown key %q
• 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/5e442b882486409e. Report an issue: GitHub.