gastownhall/beads · error

no .beads directory found

Error message

no .beads directory found

What it means

audit.Path locates the current .beads directory via beads.FindBeadsDir(). If no .beads directory can be found (not in a beads repository and none in any parent), it returns this error because the JSONL interactions sidecar has nowhere to live.

Source

Thrown at internal/audit/audit.go:59

	Response string `json:"response,omitempty"`
	Error    string `json:"error,omitempty"`

	// Tool call
	ToolName string `json:"tool_name,omitempty"`
	ExitCode *int   `json:"exit_code,omitempty"`

	// Labeling (append-only)
	ParentID string `json:"parent_id,omitempty"`
	Label    string `json:"label,omitempty"`  // "good" | "bad" | etc
	Reason   string `json:"reason,omitempty"` // human / pipeline explanation

	Extra map[string]any `json:"extra,omitempty"`
}

func Path() (string, error) {
	beadsDir := beads.FindBeadsDir()
	if beadsDir == "" {
		return "", fmt.Errorf("no .beads directory found")
	}
	return filepath.Join(beadsDir, FileName), nil
}

// Enabled reports whether the optional JSONL interaction sidecar is enabled.
// First-class issue history is always recorded in the database events tables;
// this gate only controls .beads/interactions.jsonl.
func Enabled() bool {
	if raw, ok := os.LookupEnv("BD_AUDIT_ENABLED"); ok {
		return truthy(raw)
	}
	return config.GetBool("audit.enabled")
}

func truthy(raw string) bool {
	switch strings.ToLower(strings.TrimSpace(raw)) {
	case "1", "t", "true", "y", "yes", "on":
		return true

View on GitHub (pinned to 71377f2769)

Solutions

1. Run `bd init` (or create the .beads directory) in your project root before relying on audit features
2. Run the command from inside the beads repository (or a subdirectory of it)
3. Set the beads directory explicitly if your environment supports it (e.g. BD_DIR) instead of relying on upward discovery

Example fix

// before
cd /tmp && bd doctor   // no .beads anywhere up the tree
// after
cd /path/to/project && bd init && bd doctor

dir := beads.FindBeadsDir()
if dir == "" {
    return fmt.Errorf("not inside a beads repo: run 'bd init' first")
}

p, err := audit.Path()
if err != nil {
    if err.Error() == "no .beads directory found" {
        return fmt.Errorf("run 'bd init' in your project before using audit features")
    }
    return err
}

When it happens

Trigger: Calling audit.Path(), audit.EnsureFile(), or audit.Append() outside any directory containing .beads (and with no .beads in ancestors), or when BD_DIR/discovery state is missing.

Common situations: Running bd from a scratch/temp directory, HOME misconfigured so the default beads location isn't found, or running before ever running `bd init` in the project.

Related errors

• multiple .doltcfg directories detected
• no beads configuration found in %s
• loading status configuration: %w
• failed to create .beads directory: %w
• failed to close interactions log: %w

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