gastownhall/beads · error

%s

Error message

%s

What it means

installHooksWithOptions wraps the activeWorkspaceNotFoundError message when `bd hooks install --beads-hooks` (beadsHooks mode) cannot locate a bd workspace. beads.FindBeadsDir() returns empty when no .beads directory / bd workspace exists in or above the current directory, so hook installation cannot proceed.

Source

Thrown at cmd/bd/hooks.go:875

// containing it. Errors (not a repo, path inside .git/, no work tree) count
// as untracked — the guard only blocks writes it can prove are unsafe.
func isGitTrackedFile(path string) bool {
	dir := filepath.Dir(path)
	base := filepath.Base(path)
	// #nosec G204 G702 - fixed "git" command; dir/base come from the hooks
	// directory bd itself resolved, not user input
	cmd := exec.Command("git", "-C", dir, "ls-files", "--error-unmatch", "--", base)
	return cmd.Run() == nil
}

//nolint:unparam // force and chain kept for CLI flag compatibility; section markers make them no-ops
func installHooksWithOptions(hookNames []string, force bool, shared bool, chain bool, beadsHooks bool) error {
	var hooksDir string
	if beadsHooks {
		// Use .beads/hooks/ directory (preferred for Dolt backend)
		beadsDir := beads.FindBeadsDir()
		if beadsDir == "" {
			return fmt.Errorf("%s", activeWorkspaceNotFoundError())
		}
		hooksDir = filepath.Join(beadsDir, "hooks")
	} else if shared {
		// Use versioned directory for shared hooks
		if mainRoot, err := git.GetMainRepoRoot(); err == nil && mainRoot != "" {
			hooksDir = filepath.Join(mainRoot, ".beads-hooks")
		} else {
			hooksDir = ".beads-hooks"
		}
	} else {
		// Use common git directory for hooks (shared across worktrees)
		var err error
		hooksDir, err = git.GetGitHooksDir()
		if err != nil {
			return err
		}
	}

View on GitHub (pinned to 71377f2769)

Solutions

1. Run `bd init` in the repository root to create the .beads workspace, then install hooks
2. cd to the repository root (or a directory containing .beads) and re-run the install
3. Read the wrapped message (the activeWorkspaceNotFoundError text) — it names the exact search root that failed

Example fix

// before
$ cd /tmp && bd hooks install --beads-hooks
error: no bd workspace found...
// after
$ cd ~/myproject && bd init && bd hooks install --beads-hooks

if [ -z "$(bd workspace 2>/dev/null)" ] && [ ! -d .beads ]; then echo 'run bd init first'; fi

if err := installHooksWithOptions(names, false, false, false, true); err != nil { if strings.Contains(err.Error(), "workspace") { return fmt.Errorf("run `bd init` before installing beads hooks: %w", err) }; return err }

When it happens

Trigger: Running bd hook installation with the beads hooks mode in a directory with no .beads workspace — e.g. outside a repo, before `bd init`, or in a subdirectory excluded from the workspace search.

Common situations: Running `bd hooks install` in a fresh clone before `bd init`; running from a non-repo temp directory; BEADS_DIR mis-set or the .beads dir deleted.

Related errors

• httpapi: a configured role fires this workspace's hooks; thi
• httpapi: the configured provider fires this workspace's hook
• bd %s: %w: %s
• %s
• %s; %s

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