{"record":{"id":"c52c88ffabea5a71","repo":"gastownhall/beads","slug":"failed-to-validate-git-ref-name-q-w","errorCode":null,"errorMessage":"failed to validate git ref name %q: %w","messagePattern":"failed to validate git ref name %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/worktree_cmd.go","lineNumber":1784,"sourceCode":"\tgit *worktreeRemovalGit,\n\texecutionRoot string,\n\tref string,\n\tallowOneLevel bool,\n) (bool, error) {\n\targs := []string{\"check-ref-format\"}\n\tif allowOneLevel {\n\t\targs = append(args, \"--allow-onelevel\")\n\t}\n\targs = append(args, ref)\n\t_, err := git.output(ctx, executionRoot, args...)\n\tif err == nil {\n\t\treturn true, nil\n\t}\n\tvar exitError *exec.ExitError\n\tif errors.As(err, &exitError) && exitError.ExitCode() == 1 {\n\t\treturn false, nil\n\t}\n\treturn false, fmt.Errorf(\"failed to validate git ref name %q: %w\", ref, err)\n}\n\nfunc findWorktreeComparatorRefs(\n\tctx context.Context,\n\tgit *worktreeRemovalGit,\n\texecutionRoot string,\n\tselector string,\n) ([]string, error) {\n\tcandidates := []string{\n\t\t\"refs/\" + selector,\n\t\t\"refs/tags/\" + selector,\n\t\t\"refs/heads/\" + selector,\n\t\t\"refs/remotes/\" + selector,\n\t\t\"refs/remotes/\" + selector + \"/HEAD\",\n\t}\n\tcandidateSet := make(map[string]struct{}, len(candidates))\n\tfor _, candidate := range candidates {\n\t\tcandidateSet[candidate] = struct{}{}","sourceCodeStart":1766,"sourceCodeEnd":1802,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/worktree_cmd.go#L1766-L1802","documentation":"`validateGitRefName` runs a git plumbing check to confirm a candidate ref name is valid. Exit code 1 means 'not a valid ref' (handled), but any other failure from the git subprocess is wrapped in this error with the ref name and underlying error.","triggerScenarios":"The `git for-each-ref --verify`-style validation subprocess fails with an unexpected exit code or cannot run at all — broken git installation, non-repository directory, signal-killed process, or permission problems.","commonSituations":"Running bd outside a git worktree/repository; corrupt `.git` directory; git binary missing or too old; sandbox blocking subprocess execution.","solutions":["Confirm the working directory is inside a git repository (`git rev-parse --is-inside-work-tree`)","Run the equivalent `git rev-parse --verify <ref>` manually to see the raw git error","Check that the `git` binary is installed and on PATH and works (`git --version`)","Inspect the wrapped `%w` cause for permissions or signal termination details"],"exampleFix":"// before (running from ~/Downloads, outside any repo)\nbd worktree remove --merged-into main\n// after (cd into the repository first)\ncd /path/to/repo && bd worktree remove --merged-into main","handlingStrategy":"try-catch","validationCode":"// shell pre-check\ngit rev-parse --is-inside-work-tree >/dev/null 2>&1 || echo \"not a git repository\"\ngit --version >/dev/null 2>&1 || echo \"git unavailable\"","typeGuard":null,"tryCatchPattern":"out, err := run(\"bd\", \"worktree\", \"remove\", \"--merged-into\", ref)\nif err != nil && strings.Contains(out, \"failed to validate git ref name\") {\n    // environment problem: verify repo + git install before retrying\n}","preventionTips":["Run bd from inside a valid git repository","Keep git installed and on PATH at a supported version","Check `git fsck` health if errors persist"],"tags":["git","subprocess","ref-validation","cli"],"backgroundTag":"git-command-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}