gastownhall/beads · error

worktree name %q is ambiguous; use an absolute path (matches

Error message

worktree name %q is ambiguous; use an absolute path (matches: %s)

What it means

resolveRegisteredWorktree requires an unambiguous worktree identifier. When a short name or basename matches multiple registered worktrees, it refuses to guess and lists all matching paths, asking the caller to supply an absolute path.

Source

Thrown at cmd/bd/worktree_cmd.go:920

			}
		}
		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
	pathInfo             os.FileInfo
	gitDir               string
	gitDirInfo           os.FileInfo
	gitMarkerInfo        os.FileInfo
	gitDirFingerprint    string
	gitMarkerFingerprint string
	commonDir            string
	headOID              string
	branch               string

View on GitHub (pinned to 71377f2769)

Solutions

1. Re-run with the full absolute path of the intended worktree, as printed in the error's matches list.
2. Rename one of the conflicting worktree directories so basenames are unique, then retry with the short name.
3. Use `git worktree list` to identify the stale entry and remove only that absolute path.
4. Prune the stale entry (`git worktree prune` + registry refresh) so only one match remains.

Example fix

// before
bd worktree remove feature-x
// error: worktree name "feature-x" is ambiguous; use an absolute path (matches: /a/.worktrees/feature-x, /b/.worktrees/feature-x)
// after
bd worktree remove /a/.worktrees/feature-x

const out = Bun.spawnSync(["bd", "worktree", "list", "--json"]);
const matches = JSON.parse(out.stdout.toString()).filter(w => w.path.endsWith("/feature-x"));
if (matches.length > 1) {
  throw new Error(`ambiguous: ${matches.map(m => m.path).join(", ")} — use absolute path`);
}

When it happens

Trigger: Calling `bd worktree remove <name>` where the name matches more than one registered worktree — typically two worktrees with identical basenames in different roots, or a name matching both a relative-path candidate and a basename match.

Common situations: Two worktrees with the same directory name under different roots (main repo and a fork/clone); CI and dev checkouts of the same repo on one machine; running the command from inside a worktree so current-root and main-root candidates match different entries.

Related errors

• registered worktree not found: %s
• not in a git worktree: %w
• --merged-into value %q does not name an existing unambiguous
• ErrAmbiguousID
• auto-export: git add failed: %w

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