no .beads/ directory found at %s; run 'bd init' to initializ

Error message

no .beads/ directory found at %s; run 'bd init' to initialize beads

What it means

RunPerformanceDiagnostics refuses to run when the given repository path has no .beads/ directory. Before delegating to Dolt backend diagnostics it resolves the beads directory and stats it; if it does not exist, bd has not been initialized in that repo and there is nothing to diagnose.

Source

Thrown at cmd/bd/doctor/perf.go:15

package doctor

import (
	"fmt"
	"os"
	"runtime"
	"runtime/pprof"
)

// RunPerformanceDiagnostics runs performance diagnostics.
// Delegates to Dolt backend diagnostics.
func RunPerformanceDiagnostics(path string) error {
	beadsDir := ResolveBeadsDirForRepo(path)
	if _, err := os.Stat(beadsDir); os.IsNotExist(err) {
		return fmt.Errorf("no .beads/ directory found at %s; run 'bd init' to initialize beads", path)
	}

	metrics, err := RunDoltPerformanceDiagnostics(path, true)
	if err != nil {
		return fmt.Errorf("running performance diagnostics: %w", err)
	}
	PrintDoltPerfReport(metrics)
	return nil
}

// CollectPlatformInfo gathers platform information for diagnostics.
func CollectPlatformInfo(path string) map[string]string {
	info := make(map[string]string)
	info["os_arch"] = fmt.Sprintf("%s/%s", runtime.GOOS, runtime.GOARCH)
	info["go_version"] = runtime.Version()

	beadsDir := ResolveBeadsDirForRepo(path)
	if IsDoltBackend(beadsDir) {

View on GitHub (pinned to 71377f2769)

Solutions

cd into the repository root (or pass the correct path) so the .beads/ directory is found
Run 'bd init' in the target repository to create .beads/
Verify the path exists and contains .beads/: ls <path>/.beads

Example fix

// before
RunPerformanceDiagnostics("~/some-repo")
// after
if _, err := os.Stat(filepath.Join(repo, ".beads")); err == nil {
    RunPerformanceDiagnostics(repo)
} else {
    exec.Command("bd", "init").Run()
}

Defensive patterns

Strategy: validation

Validate before calling

func hasBeadsDir(repo string) bool {
    _, err := os.Stat(filepath.Join(repo, ".beads"))
    return err == nil
}
if !hasBeadsDir(repo) { exec.Command("bd", "init").Run() }

Try / catch

if err := RunPerformanceDiagnostics(repo); err != nil && strings.Contains(err.Error(), "no .beads/ directory") {
    // run bd init or abort
}

Prevention

Always resolve the repo root before invoking bd doctor commands
Run 'bd init' as part of repo bootstrap/CI setup
Never gitignore .beads/ if tooling expects it present after clone

When it happens

Trigger: Calling RunPerformanceDiagnostics(path) (via 'bd doctor' performance checks) on a directory where ResolveBeadsDirForRepo(path) points at a .beads/ dir that does not exist — i.e. 'bd init' was never run there, or the path points at the wrong repo root.

Common situations: Running bd doctor from a parent or sibling directory instead of the repo root; a freshly cloned repo where .beads/ was gitignored and never created; a typo'd --path; running in CI before an init step.

Related errors

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