gastownhall/beads · error

failed to inspect symbolic ref %q: %w

Error message

failed to inspect symbolic ref %q: %w

What it means

bd runs `git symbolic-ref --quiet <ref>` to walk the symbolic ref chain. Exit code 1 means the ref is terminal (not symbolic) and is handled normally; any other failure means the ref could not be inspected at all (git crashed, bad invocation, context cancellation, filesystem error). This error wraps that unexpected underlying failure.

Source

Thrown at cmd/bd/worktree_cmd.go:1926

		if _, duplicate := seen[current]; duplicate {
			return "", fmt.Errorf("symbolic ref cycle while resolving %q", ref)
		}
		seen[current] = struct{}{}

		output, err := git.output(ctx, executionRoot, "symbolic-ref", "--quiet", current)
		if err == nil {
			next := strings.TrimSpace(string(output))
			if !strings.HasPrefix(next, "refs/") {
				return "", fmt.Errorf("symbolic ref %q resolves outside refs/: %q", current, next)
			}
			current = next
			continue
		}
		var exitError *exec.ExitError
		if errors.As(err, &exitError) && exitError.ExitCode() == 1 {
			return current, nil
		}
		return "", fmt.Errorf("failed to inspect symbolic ref %q: %w", current, err)
	}
	return "", fmt.Errorf("symbolic ref chain for %q exceeds 16 links", ref)
}

func resolveWorktreeCommitOID(
	ctx context.Context,
	git *worktreeRemovalGit,
	executionRoot string,
	refOrOID string,
) (string, error) {
	output, err := git.output(
		ctx,
		executionRoot,
		"rev-parse",
		"--verify",
		"--quiet",
		"--end-of-options",
		refOrOID+"^{commit}",

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the wrapped `%w` cause in the error message to identify the underlying git failure
2. Verify the working directory is a valid git repository: `git rev-parse --git-dir`
3. Check that the git binary is installed and healthy: `git --version`
4. Re-run after resolving cancellation causes (timeout, Ctrl-C) if the wrapped cause is a context error

Example fix

// before: running bd where git cannot resolve the repo
$ bd worktree remove mywt
error: failed to inspect symbolic ref "refs/heads/x": fatal: not a git repository
// after: run from the repo root (or a valid worktree)
$ cd /path/to/repo && bd worktree remove mywt

// verify git and repo health before running bd worktree commands
if err := exec.Command("git", "rev-parse", "--git-dir").Run(); err != nil {
	return fmt.Errorf("not inside a valid git repository: %w", err)
}
if err := exec.Command("git", "--version").Run(); err != nil {
	return fmt.Errorf("git binary unavailable: %w", err)
}

_, err := bd.WorktreeRemove(name)
if err != nil {
	var wrapped interface{ Unwrap() error }
	if errors.As(err, &wrapped) && errors.Is(wrapped, context.Canceled) {
		return fmt.Errorf("operation canceled: %w", err)
	}
	if strings.Contains(err.Error(), "failed to inspect symbolic ref") {
		return fmt.Errorf("git/repository unhealthy; run `git fsck` and check PATH: %w", err)
	}
	return err
}

When it happens

Trigger: `git symbolic-ref` fails with a non-1 exit code during `resolveWorktreeTerminalRef` — e.g. git binary missing/broken, the execution root is not a git repository, the command is killed (context canceled), or the ref file is unreadable.

Common situations: Running bd outside a valid git repo or with a corrupted .git directory; PATH pointing to an incompatible git version; OS-level permission problems on the repo; command canceled by timeout or Ctrl-C.

Related errors

• symbolic ref cycle while resolving %q
• symbolic ref %q resolves outside refs/: %q
• symbolic ref chain for %q exceeds 16 links
• failed to inspect created worktree cleanliness: %w %s
• created worktree is dirty after checkout; refusing to contin

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