{"record":{"id":"945302a72a2992c0","repo":"gastownhall/beads","slug":"failed-to-inspect-symbolic-ref-q-w","errorCode":null,"errorMessage":"failed to inspect symbolic ref %q: %w","messagePattern":"failed to inspect symbolic ref %q: %w","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/worktree_cmd.go","lineNumber":1926,"sourceCode":"\t\tif _, duplicate := seen[current]; duplicate {\n\t\t\treturn \"\", fmt.Errorf(\"symbolic ref cycle while resolving %q\", ref)\n\t\t}\n\t\tseen[current] = struct{}{}\n\n\t\toutput, err := git.output(ctx, executionRoot, \"symbolic-ref\", \"--quiet\", current)\n\t\tif err == nil {\n\t\t\tnext := strings.TrimSpace(string(output))\n\t\t\tif !strings.HasPrefix(next, \"refs/\") {\n\t\t\t\treturn \"\", fmt.Errorf(\"symbolic ref %q resolves outside refs/: %q\", current, next)\n\t\t\t}\n\t\t\tcurrent = next\n\t\t\tcontinue\n\t\t}\n\t\tvar exitError *exec.ExitError\n\t\tif errors.As(err, &exitError) && exitError.ExitCode() == 1 {\n\t\t\treturn current, nil\n\t\t}\n\t\treturn \"\", fmt.Errorf(\"failed to inspect symbolic ref %q: %w\", current, err)\n\t}\n\treturn \"\", fmt.Errorf(\"symbolic ref chain for %q exceeds 16 links\", ref)\n}\n\nfunc resolveWorktreeCommitOID(\n\tctx context.Context,\n\tgit *worktreeRemovalGit,\n\texecutionRoot string,\n\trefOrOID string,\n) (string, error) {\n\toutput, err := git.output(\n\t\tctx,\n\t\texecutionRoot,\n\t\t\"rev-parse\",\n\t\t\"--verify\",\n\t\t\"--quiet\",\n\t\t\"--end-of-options\",\n\t\trefOrOID+\"^{commit}\",","sourceCodeStart":1908,"sourceCodeEnd":1944,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/worktree_cmd.go#L1908-L1944","documentation":"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.","triggerScenarios":"`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.","commonSituations":"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.","solutions":["Read the wrapped `%w` cause in the error message to identify the underlying git failure","Verify the working directory is a valid git repository: `git rev-parse --git-dir`","Check that the git binary is installed and healthy: `git --version`","Re-run after resolving cancellation causes (timeout, Ctrl-C) if the wrapped cause is a context error"],"exampleFix":"// before: running bd where git cannot resolve the repo\n$ bd worktree remove mywt\nerror: failed to inspect symbolic ref \"refs/heads/x\": fatal: not a git repository\n// after: run from the repo root (or a valid worktree)\n$ cd /path/to/repo && bd worktree remove mywt","handlingStrategy":"try-catch","validationCode":"// verify git and repo health before running bd worktree commands\nif err := exec.Command(\"git\", \"rev-parse\", \"--git-dir\").Run(); err != nil {\n\treturn fmt.Errorf(\"not inside a valid git repository: %w\", err)\n}\nif err := exec.Command(\"git\", \"--version\").Run(); err != nil {\n\treturn fmt.Errorf(\"git binary unavailable: %w\", err)\n}","typeGuard":null,"tryCatchPattern":"_, err := bd.WorktreeRemove(name)\nif err != nil {\n\tvar wrapped interface{ Unwrap() error }\n\tif errors.As(err, &wrapped) && errors.Is(wrapped, context.Canceled) {\n\t\treturn fmt.Errorf(\"operation canceled: %w\", err)\n\t}\n\tif strings.Contains(err.Error(), \"failed to inspect symbolic ref\") {\n\t\treturn fmt.Errorf(\"git/repository unhealthy; run `git fsck` and check PATH: %w\", err)\n\t}\n\treturn err\n}","preventionTips":["Run bd from a valid git repository or worktree root","Keep a healthy git binary on PATH compatible with your repo","Avoid killing commands mid-run; use bd's cancellation handling","Run `git fsck` periodically on repos managed by automation"],"tags":["git","command-execution","symbolic-ref","worktree"],"backgroundTag":"git-command-execution-failed","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}