gastownhall/beads · error

node %q has empty title

Error message

node %q has empty title

What it means

Plan validation requires every node in plan.nodes to have a non-empty `title`. A node with an empty title is rejected before any issue is created, since titles are required fields for beads issues.

Source

Thrown at cmd/bd/graph_apply.go:540

}

func validateGraphApplyPlan(plan *GraphApplyPlan, customTypes, customStatuses []string, opts GraphApplyOptions) error {
	if len(plan.Nodes) == 0 {
		return fmt.Errorf("plan has no nodes")
	}

	seenKeys := make(map[string]bool, len(plan.Nodes))
	seenIDs := make(map[string]bool)
	for i, node := range plan.Nodes {
		if node.Key == "" {
			return fmt.Errorf("node %d has empty key", i)
		}
		if seenKeys[node.Key] {
			return fmt.Errorf("duplicate node key %q", node.Key)
		}
		seenKeys[node.Key] = true
		if node.Title == "" {
			return fmt.Errorf("node %q has empty title", node.Key)
		}
		if err := validateGraphApplyNodeFields(node, customTypes, customStatuses, opts); err != nil {
			return err
		}
		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

View on GitHub (pinned to 71377f2769)

Solutions

1. Set a descriptive title on the node flagged in the error
2. If the node is unwanted, remove it from plan.nodes entirely
3. Fix the generating script/template so titles are always filled

Example fix

// before
{"key": "auth-login", "title": ""}
// after
{"key": "auth-login", "title": "Implement login endpoint"}

for i, n := range plan.Nodes {
	if strings.TrimSpace(n.Title) == "" { return fmt.Errorf("node %d (%s) missing title", i, n.Key) }
}

if err := bd.GraphApply(ctx, plan, opts); err != nil {
	if strings.Contains(err.Error(), "has empty title") {
		// fill title in plan and retry
	}
}

When it happens

Trigger: `bd graph apply` with a plan where a node object has `"title": ""` or omits the title field.

Common situations: Generated plans where the title field was never populated; hand-edited plan files where a title was accidentally cleared; template placeholders left unfilled.

Understand the failure class

Background: "Missing required field" and "field is required" errors: why libraries reject payloads that omit mandatory fields — this error's family across 20 libraries.

Related errors

• node %q: dep %d has empty target
• edge %d: must specify from_key or from_id
• duplicate node key %q
• duplicate explicit id %q (node %q)
• node %q: metadata ref %q references unknown key %q

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