gastownhall/beads · error

git worktree registry is empty

Error message

git worktree registry is empty

What it means

After parsing `git worktree list --porcelain -z`, listRegisteredWorktrees asserts the registry contains at least one entry (git always reports the main working tree). An empty list means git returned success but no worktrees — a logically impossible state signaling repo metadata corruption or an unexpected git output format, so bd fails closed rather than removing anything.

Source

Thrown at cmd/bd/worktree_cmd.go:807

			current.detached = true
		case field == "bare":
			current.bare = true
		case field == "locked":
			current.locked = true
		case strings.HasPrefix(field, "locked "):
			current.locked = true
			current.lockReason = strings.TrimPrefix(field, "locked ")
		case field == "prunable":
			current.prunable = true
		case strings.HasPrefix(field, "prunable "):
			current.prunable = true
			current.pruneReason = strings.TrimPrefix(field, "prunable ")
		}
	}
	appendCurrent()

	if len(worktrees) == 0 {
		return nil, fmt.Errorf("git worktree registry is empty")
	}
	return worktrees, nil
}

func sameWorktreePath(left, right string) bool {
	leftAbsolute, leftErr := filepath.Abs(left)
	rightAbsolute, rightErr := filepath.Abs(right)
	if leftErr != nil || rightErr != nil {
		return false
	}
	leftAbsolute = filepath.Clean(leftAbsolute)
	rightAbsolute = filepath.Clean(rightAbsolute)

	// When both paths are missing, peel exact components in lockstep until
	// existing ancestors can prove physical identity. This accepts equivalent
	// ancestor spellings such as a Windows 8.3 alias without ever case-folding
	// an unresolved component.
	for {

View on GitHub (pinned to 71377f2769)

Solutions

1. Verify git works: run `git worktree list --porcelain` and check output manually
2. Check which git is in PATH (`which git`) and ensure it's official git, not a shim
3. Run `git fsck` to check repository integrity; restore from a clone if corrupt
4. Update git to a current version and retry

Example fix

// before
bd worktree remove wt-x   # git worktree registry is empty
// after
which git   # found nonstandard shim
export PATH=/usr/bin:$PATH
bd worktree remove wt-x

n=$(git worktree list --porcelain | grep -c '^worktree ' || true)
[ "$n" -ge 1 ] || { echo "registry unexpectedly empty"; exit 1; }

if len(worktrees) == 0 {
    // fail closed: refuse removal when the registry is unparseable/empty
    return fmt.Errorf("git worktree registry is empty")
}

worktrees, err := listRegisteredWorktrees(ctx, g, root)
if err != nil || len(worktrees) == 0 {
    return fmt.Errorf("cannot verify worktree registry; aborting removal")
}

When it happens

Trigger: `git worktree list --porcelain -z` succeeds but yields zero parseable worktree entries — e.g. a heavily corrupted repository, a git version producing unexpected porcelain output, or output being swallowed/truncated by an unusual environment (GIT_PAGER or alternative git shim in PATH).

Common situations: Git shim/wrapper binaries (e.g. custom gits in PATH) emitting non-porcelain output; corrupted .git where even the main worktree entry is missing; exotic git builds or downgrade to a very old git.

Related errors

• failed to inspect created worktree cleanliness: %w %s
• created worktree is dirty after checkout; refusing to contin
• worktree not found: %s
• failed to read git worktree registry: %w
• failed to parse backup state: %w

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