gastownhall/beads · error

duplicate explicit id %q (node %q)

Error message

duplicate explicit id %q (node %q)

What it means

Nodes may carry an optional explicit `id`. Validation tracks explicit IDs in a set and rejects a plan when two nodes specify the same ID, since duplicate IDs would collide when creating/patching issues. The error names both the duplicate ID and the offending node key.

Source

Thrown at cmd/bd/graph_apply.go:547

	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
					}
				}
				if !found {
					return fmt.Errorf("node %q: metadata ref %q references unknown key %q", node.Key, metaKey, refKey)
				}
			}
		}

View on GitHub (pinned to 71377f2769)

Solutions

1. Give one of the nodes a distinct explicit id
2. Remove the explicit id from the new node so the system assigns one automatically
3. Ensure generated plans derive ids deterministically and uniquely (e.g. by key)

Example fix

// before
{"key": "a", "id": "bd-100"}, {"key": "b", "id": "bd-100"}
// after
{"key": "a", "id": "bd-100"}, {"key": "b"}

ids := map[string]bool{}
for _, n := range plan.Nodes {
	if n.ID != "" {
		if ids[n.ID] { return fmt.Errorf("duplicate explicit id %q", n.ID) }
		ids[n.ID] = true
	}
}

if err := bd.GraphApply(ctx, plan, opts); err != nil {
	if strings.Contains(err.Error(), "duplicate explicit id") {
		// strip or rename ids and retry
	}
}

When it happens

Trigger: `bd graph apply` with a plan where two nodes set the same non-empty `id` field.

Common situations: Copy-pasting a node block including its explicit id; importing an existing plan and duplicating entries; ids copied from a previous plan without adjusting for re-use.

Related errors

• duplicate node key %q
• node %q has empty title
• node %q: metadata ref %q references unknown key %q
• node %q: parent key %q not found in plan
• node %q: dep %d has empty target

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