gastownhall/beads · error

reading hook file: %w

Error message

reading hook file: %w

What it means

Wraps a scanner error encountered while reading a git hook file line-by-line in getHookVersion. It indicates the hook file could not be fully read (I/O error), not that its version is unknown. The wrapped cause identifies the read failure.

Source

Thrown at cmd/bd/hooks.go:599

			after = strings.TrimPrefix(after, "v")
			after = strings.TrimSuffix(after, "---")
			version := strings.TrimSpace(after)
			return hookVersionInfo{Version: version, IsShim: true, IsBdHook: true}, nil
		}
		// Check for thin shim marker first
		if strings.HasPrefix(line, shimVersionPrefix) {
			version := strings.TrimSpace(strings.TrimPrefix(line, shimVersionPrefix))
			return hookVersionInfo{Version: version, IsShim: true, IsBdHook: true}, nil
		}
		// Check for legacy version marker
		if strings.HasPrefix(line, hookVersionPrefix) {
			version := strings.TrimSpace(strings.TrimPrefix(line, hookVersionPrefix))
			return hookVersionInfo{Version: version, IsShim: false, IsBdHook: true}, nil
		}
	}

	if err := scanner.Err(); err != nil {
		return hookVersionInfo{}, fmt.Errorf("reading hook file: %w", err)
	}

	// Check if it's an inline bd hook (from bd init) - GH#1120
	// These don't have version markers but have "# bd (beads)" comment
	if strings.Contains(content.String(), inlineHookMarker) {
		return hookVersionInfo{IsBdHook: true}, nil
	}

	// No version found and not a bd hook
	return hookVersionInfo{}, nil
}

// FormatHookWarnings returns a formatted warning message if hooks are outdated
func FormatHookWarnings(statuses []HookStatus) string {
	var warnings []string

	missingCount := 0
	outdatedCount := 0

View on GitHub (pinned to 71377f2769)

Solutions

1. Fix file permissions on .git/hooks/<hook> (chmod u+r or re-own the file).
2. Remove the broken hook file and re-run bd init / bd hooks install to reinstall it.
3. Check disk/filesystem health if the wrapped cause indicates I/O errors.

Example fix

// before
$ bd hooks install
// error: reading hook file: open .git/hooks/pre-commit: permission denied
// after
$ chmod u+r .git/hooks/pre-commit  # or: rm -f .git/hooks/pre-commit
$ bd hooks install

if fi, err := os.Stat(hookPath); err != nil || !fi.Mode().IsRegular() {
	return errors.New("hook file unreadable or not a regular file")
}

info, err := getHookVersion(hookPath)
if err != nil && strings.HasPrefix(err.Error(), "reading hook file:") {
	// fall back to treating the hook as unknown/foreign
}

When it happens

Trigger: scanner.Err() is non-nil after scanning the hook file during getHookVersion, called from CheckGitHooks, isBdOwnedHookFile, installHooksWithOptions, uninstallHooks, or runChainedHook.

Common situations: Hook file permissions deny reading (permission denied), the file is deleted/truncated mid-scan, disk I/O errors, or a file replaced by a FIFO/device that errors on read.

Related errors

• failed to stat %s: %w
• failed to read .gitignore: %w
• failed to remove emptied .gitignore: %w
• writing migrated hook %s: %w
• checking source sidecar %s: %w

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