gastownhall/beads · error

failed to read git worktree registry: %w

Error message

failed to read git worktree registry: %w

What it means

listRegisteredWorktrees reads the git worktree registry via `git worktree list --porcelain -z` before any removal, to validate the target. If the git call fails (non-zero exit with stderr, per the output() wrapper), the failure is wrapped with this message. bd needs the authoritative registry to safely prune the right worktree.

Source

Thrown at cmd/bd/worktree_cmd.go:762

	headOID     string
	branch      string
	detached    bool
	bare        bool
	locked      bool
	lockReason  string
	prunable    bool
	pruneReason string
	isMain      bool
}

func listRegisteredWorktrees(
	ctx context.Context,
	git *worktreeRemovalGit,
	executionRoot string,
) ([]registeredWorktree, error) {
	output, err := git.output(ctx, executionRoot, "worktree", "list", "--porcelain", "-z")
	if err != nil {
		return nil, fmt.Errorf("failed to read git worktree registry: %w", err)
	}

	var worktrees []registeredWorktree
	var current registeredWorktree
	appendCurrent := func() {
		if current.path == "" {
			return
		}
		current.isMain = len(worktrees) == 0
		worktrees = append(worktrees, current)
		current = registeredWorktree{}
	}

	for _, field := range strings.Split(string(output), "\x00") {
		if field == "" {
			continue
		}
		switch {

View on GitHub (pinned to 71377f2769)

Solutions

1. Run `git worktree list` manually in the repo to see git's error
2. Clear stale locks (rm .git/index.lock) if a crash left them behind
3. Run `git worktree prune` to clean dangling registrations, then retry
4. Verify the execution root is the repository (not a deleted worktree path)

Example fix

// before
bd worktree remove wt-x   # failed to read git worktree registry: ... index.lock
// after
rm -f .git/index.lock
git worktree prune
bd worktree remove wt-x

git worktree list --porcelain >/dev/null 2>&1 || { echo "worktree registry unreadable"; exit 1; }

if _, err := listRegisteredWorktrees(ctx, g, root); err != nil {
    var ee *exec.ExitError
    if errors.As(err, &ee) {
        // inspect git stderr embedded by the output() wrapper, fix, then retry
    }
    return err
}

When it happens

Trigger: prepareWorktreeRemoval / revalidation / removal-failure observation call listRegisteredWorktrees and the underlying `git worktree list --porcelain -z` exits non-zero — corrupt repo, locked index, invalid GIT_DIR remnants, or git binary failure.

Common situations: Broken .git/worktrees metadata after interrupted operations; concurrent git processes holding locks; running with a scrubbed environment in a directory that isn't a repository.

Related errors

• failed to inspect created worktree cleanliness: %w %s
• created worktree is dirty after checkout; refusing to contin
• worktree not found: %s
• git worktree registry is empty
• failed to init git in planning repo: %w

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