What causes "registered worktree not found: %s" in gastownhall/beads?

Run `git worktree list` and `bd worktree list` to see registered worktrees, then use an exact registered name or path.

registered worktree not found: %s

Error message

registered worktree not found: %s

What it means

resolveRegisteredWorktree matches the user-supplied name/path against the bd worktree registry. When zero entries match, it returns this error instead of proceeding to removal. It means the identifier given to `bd worktree remove` does not correspond to any registered worktree.

Source

Thrown at cmd/bd/worktree_cmd.go:911

		if !matched {
			continue
		}

		duplicate := false
		for _, existing := range matches {
			if sameWorktreePath(existing.path, worktree.path) {
				duplicate = true
				break
			}
		}
		if !duplicate {
			matches = append(matches, worktree)
		}
	}

	switch len(matches) {
	case 0:
		return registeredWorktree{}, fmt.Errorf("registered worktree not found: %s", name)
	case 1:
		return matches[0], nil
	default:
		paths := make([]string, 0, len(matches))
		for _, match := range matches {
			paths = append(paths, match.path)
		}
		sort.Strings(paths)
		return registeredWorktree{}, fmt.Errorf(
			"worktree name %q is ambiguous; use an absolute path (matches: %s)",
			name,
			strings.Join(paths, ", "),
		)
	}
}

type pinnedWorktreeTarget struct {
	path                 string

View on GitHub (pinned to 71377f2769)

Solutions

Run `git worktree list` and `bd worktree list` to see registered worktrees, then use an exact registered name or path.
Pass the absolute path of the worktree instead of a basename: `bd worktree remove /abs/path/to/worktree`.
If the worktree was deleted manually, run `git worktree prune` and re-sync the bd registry, then retry.
Re-create the worktree with `bd worktree add <name>` if it never existed.

Example fix

// before
bd worktree remove feature-x
// error: registered worktree not found: feature-x
// after
bd worktree list                    # find exact registered path
bd worktree remove /repo/.worktrees/feature-x

Defensive patterns

Strategy: validation

Validate before calling

const out = Bun.spawnSync(["bd", "worktree", "list", "--json"]);
const registered = JSON.parse(out.stdout.toString()).map(w => w.path);
const target = "/repo/.worktrees/feature-x";
if (!registered.some(p => p === target || p.endsWith("/" + target))) {
  throw new Error(`worktree not registered: ${target}`);
}

Type guard

function isRegistered(path, registered) {
  return registered.some(w => w.path === path || w.name === path);
}

Prevention

Always list registered worktrees (`bd worktree list`) before removing.
Use absolute paths instead of short names in scripts.
Register manually created worktrees with bd before referencing them.
Prune after manually deleting worktree directories.

When it happens

Trigger: Calling `bd worktree remove <name>` where <name> is neither an absolute path matching a registered worktree, nor resolves (relative to current root or main root) to one, nor matches any registered worktree directory basename.

Common situations: Typo in the worktree name; worktree already removed or pruned; worktree created manually with `git worktree add` and never registered with bd; running from a different repo root so relative candidates resolve elsewhere; registry reset after a re-clone.

Related errors

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