gastownhall/beads · error

failed to install hooks: %w

Error message

failed to install hooks: %w

What it means

GitHooks shells out to `bd hooks install` (newBdCmd with cmd.Dir set to the target path) and wraps any non-zero exit as "failed to install hooks: %w". The child's stdout/stderr are already streamed to the terminal, so the wrapped cause plus that output tells you exactly why the hook install failed.

Source

Thrown at cmd/bd/doctor/fix/hooks.go:634

	}

	// Build command arguments
	// Use --force to cleanly replace outdated hooks without creating backups (GH#1466)
	args := []string{"hooks", "install", "--force"}

	// If external hook managers detected, use --chain to preserve them
	if len(externalManagers) > 0 {
		args = append(args, "--chain")
	}

	// Run bd hooks install
	cmd := newBdCmd(bdBinary, args...)
	cmd.Dir = path // Set working directory without changing process dir
	cmd.Stdout = os.Stdout
	cmd.Stderr = os.Stderr

	if err := cmd.Run(); err != nil {
		return fmt.Errorf("failed to install hooks: %w", err)
	}

	return nil
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Read the streamed stderr from the `bd hooks install` output above the error and fix that specific cause
2. Run `bd hooks install` manually inside the repo to reproduce and see the raw failure
3. Check write permission on .git/hooks and resolve external hook-manager conflicts (husky/lefthook) before installing

Example fix

// before
$ bd doctor  # failed to install hooks: exit status 1 (permission denied writing .git/hooks/pre-commit)
// after
$ sudo chown -R $(whoami) .git/hooks
$ bd hooks install

// Verify the bd binary supports the hooks subcommand and hooks dir is writable
if err := exec.Command(bdBinary, "hooks", "--help").Run(); err != nil {
	return fmt.Errorf("bd binary %s lacks hooks support", bdBinary)
}
if f, err := os.OpenFile(filepath.Join(path, ".git", "hooks", ".probe"), os.O_CREATE|os.O_WRONLY, 0o755); err != nil {
	return fmt.Errorf(".git/hooks not writable: %w", err)
} else { f.Close(); os.Remove(filepath.Join(path, ".git", "hooks", ".probe")) }

if err := fix.GitHooks(path, bdBinary); err != nil {
	var exitErr *exec.ExitError
	if errors.As(err, &exitErr) {
		log.Printf("bd hooks install exited %d; see streamed output above for the cause", exitErr.ExitCode())
	}
	return err
}

When it happens

Trigger: Running the hooks fix when the `bd hooks install` subprocess exits non-zero: unknown or invalid hook flags/path, the bd binary found is broken or an incompatible version, permission denied writing .git/hooks, or the target stopped being a valid repo between the git check and install.

Common situations: Outdated bd binary on PATH that lacks the hooks subcommand; read-only or root-owned .git/hooks directory; hook conflicts with husky/lefthook/other managers refusing to overwrite; interrupted git repo state.

Related errors

• not a git repository
• git config --unset core.hooksPath failed: %w (output: %s)
• reading git log: %w
• bd %s: %w: %s
• failed to untrack redirect file: %w

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