{"record":{"id":"1ac33dcdfc34b26f","repo":"gastownhall/beads","slug":"worktree-name-q-is-ambiguous-use-an-absolute-pat","errorCode":null,"errorMessage":"worktree name %q is ambiguous; use an absolute path (matches: %s)","messagePattern":"worktree name %q is ambiguous; use an absolute path \\(matches: (.+?)\\)","errorType":"console","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/worktree_cmd.go","lineNumber":920,"sourceCode":"\t\t\t}\n\t\t}\n\t\tif !duplicate {\n\t\t\tmatches = append(matches, worktree)\n\t\t}\n\t}\n\n\tswitch len(matches) {\n\tcase 0:\n\t\treturn registeredWorktree{}, fmt.Errorf(\"registered worktree not found: %s\", name)\n\tcase 1:\n\t\treturn matches[0], nil\n\tdefault:\n\t\tpaths := make([]string, 0, len(matches))\n\t\tfor _, match := range matches {\n\t\t\tpaths = append(paths, match.path)\n\t\t}\n\t\tsort.Strings(paths)\n\t\treturn registeredWorktree{}, fmt.Errorf(\n\t\t\t\"worktree name %q is ambiguous; use an absolute path (matches: %s)\",\n\t\t\tname,\n\t\t\tstrings.Join(paths, \", \"),\n\t\t)\n\t}\n}\n\ntype pinnedWorktreeTarget struct {\n\tpath                 string\n\tpathInfo             os.FileInfo\n\tgitDir               string\n\tgitDirInfo           os.FileInfo\n\tgitMarkerInfo        os.FileInfo\n\tgitDirFingerprint    string\n\tgitMarkerFingerprint string\n\tcommonDir            string\n\theadOID              string\n\tbranch               string","sourceCodeStart":902,"sourceCodeEnd":938,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/worktree_cmd.go#L902-L938","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Re-run with the full absolute path of the intended worktree, as printed in the error's matches list.","Rename one of the conflicting worktree directories so basenames are unique, then retry with the short name.","Use `git worktree list` to identify the stale entry and remove only that absolute path.","Prune the stale entry (`git worktree prune` + registry refresh) so only one match remains."],"exampleFix":"// before\nbd worktree remove feature-x\n// error: worktree name \"feature-x\" is ambiguous; use an absolute path (matches: /a/.worktrees/feature-x, /b/.worktrees/feature-x)\n// after\nbd worktree remove /a/.worktrees/feature-x","handlingStrategy":"validation","validationCode":"const out = Bun.spawnSync([\"bd\", \"worktree\", \"list\", \"--json\"]);\nconst matches = JSON.parse(out.stdout.toString()).filter(w => w.path.endsWith(\"/feature-x\"));\nif (matches.length > 1) {\n  throw new Error(`ambiguous: ${matches.map(m => m.path).join(\", \")} — use absolute path`);\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Keep worktree directory basenames unique across a machine.","In automation, always target absolute paths.","Avoid running removal from inside a different worktree root where relative resolution can multi-match.","Clean stale registry entries so duplicates disappear."],"tags":["worktree","git","ambiguity","cli"],"backgroundTag":"ambiguous-identifier","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}