What causes "failed to validate git ref name %q: %w" in gastownhall/beads?

Confirm the working directory is inside a git repository (`git rev-parse --is-inside-work-tree`)

failed to validate git ref name %q: %w

Error message

failed to validate git ref name %q: %w

What it means

`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.

Source

Thrown at cmd/bd/worktree_cmd.go:1784

	git *worktreeRemovalGit,
	executionRoot string,
	ref string,
	allowOneLevel bool,
) (bool, error) {
	args := []string{"check-ref-format"}
	if allowOneLevel {
		args = append(args, "--allow-onelevel")
	}
	args = append(args, ref)
	_, err := git.output(ctx, executionRoot, args...)
	if err == nil {
		return true, nil
	}
	var exitError *exec.ExitError
	if errors.As(err, &exitError) && exitError.ExitCode() == 1 {
		return false, nil
	}
	return false, fmt.Errorf("failed to validate git ref name %q: %w", ref, err)
}

func findWorktreeComparatorRefs(
	ctx context.Context,
	git *worktreeRemovalGit,
	executionRoot string,
	selector string,
) ([]string, error) {
	candidates := []string{
		"refs/" + selector,
		"refs/tags/" + selector,
		"refs/heads/" + selector,
		"refs/remotes/" + selector,
		"refs/remotes/" + selector + "/HEAD",
	}
	candidateSet := make(map[string]struct{}, len(candidates))
	for _, candidate := range candidates {
		candidateSet[candidate] = struct{}{}

View on GitHub (pinned to 71377f2769)

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

Example fix

// before (running from ~/Downloads, outside any repo)
bd worktree remove --merged-into main
// after (cd into the repository first)
cd /path/to/repo && bd worktree remove --merged-into main

Defensive patterns

Strategy: try-catch

Validate before calling

// shell pre-check
git rev-parse --is-inside-work-tree >/dev/null 2>&1 || echo "not a git repository"
git --version >/dev/null 2>&1 || echo "git unavailable"

Try / catch

out, err := run("bd", "worktree", "remove", "--merged-into", ref)
if err != nil && strings.Contains(out, "failed to validate git ref name") {
    // environment problem: verify repo + git install before retrying
}

Prevention

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

When it happens

Trigger: 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.

Common situations: Running bd outside a git worktree/repository; corrupt `.git` directory; git binary missing or too old; sandbox blocking subprocess execution.

Related errors

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