What causes "no .beads/config.yaml found (run 'bd init' first)" in gastownhall/beads?

Run 'bd init' in the project root to create .beads/config.yaml

no .beads/config.yaml found (run 'bd init' first)

Error message

no .beads/config.yaml found (run 'bd init' first)

What it means

findProjectConfigYamlWithFinder returns this error when no BEADS_DIR override applies and no .beads/config.yaml can be located in the project (via finder or loaded state). It is the terminal 'project not initialized' condition for YAML config writes.

Solutions

Run 'bd init' in the project root to create .beads/config.yaml
cd into the repository/project that contains .beads/config.yaml before running config commands
If the config lives elsewhere, set BEADS_DIR to the directory containing config.yaml
Restore a deleted .beads/config.yaml (e.g., from git history if it was tracked)

Example fix

// before (fails in bare repo)
$ cd ~/newproject && bd config set hierarchy.max-depth 5
no .beads/config.yaml found (run 'bd init' first)
// after
$ cd ~/newproject && bd init && bd config set hierarchy.max-depth 5

Defensive patterns

Strategy: validation

Validate before calling

if os.Getenv("BEADS_DIR") == "" {
    if _, err := os.Stat(".beads/config.yaml"); os.IsNotExist(err) {
        return fmt.Errorf("not an initialized beads project: run 'bd init'")
    }
}

Type guard

func inBeadsProject() bool {
    _, err := os.Stat(".beads/config.yaml")
    return err == nil
}

Try / catch

if err := SetYamlConfig(key, value); err != nil {
    if strings.Contains(err.Error(), "no .beads/config.yaml found") {
        // cd to project root or run bd init, then retry
    }
    return err
}

Prevention

Run bd config commands from the project root (or any directory with .beads/config.yaml up the tree)
Run 'bd init' in every fresh clone before configuring
Don't delete or gitignore .beads/config.yaml if project-local config is required

When it happens

Trigger: Calling SetYamlConfig / UnsetYamlConfig (via findProjectConfigYaml) from a directory chain with no .beads/config.yaml, with BEADS_DIR unset, and no config path recorded in loaded state.

Common situations: Running 'bd config set' outside any initialized beads project; running from a subdirectory whose repo lacks .beads/; after deleting .beads/config.yaml; forgetting 'bd init' in a fresh clone.

Related errors

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

Appendix: source

Thrown at internal/config/yaml_config.go:602

			return configPath, nil
		}
		return "", fmt.Errorf("no config.yaml found in BEADS_DIR (%s) (run 'bd init' first)", beadsDir)
	}

	if configPath := projectConfigPathFromLoadedState(); configPath != "" {
		return configPath, nil
	}

	if findBeadsDir != nil {
		if beadsDir := findBeadsDir(); beadsDir != "" {
			configPath := filepath.Join(beadsDir, "config.yaml")
			if _, err := os.Stat(configPath); err == nil {
				return configPath, nil
			}
		}
	}

	return "", fmt.Errorf("no .beads/config.yaml found (run 'bd init' first)")
}

func projectConfigPathFromLoadedState() string {
	configPath := ConfigFileUsed()
	if configPath == "" {
		return ""
	}
	if filepath.Base(configPath) != "config.yaml" {
		return ""
	}
	if filepath.Base(filepath.Dir(configPath)) != ".beads" {
		return ""
	}
	if _, err := os.Stat(configPath); err != nil {
		return ""
	}
	return configPath
}

View on GitHub (pinned to 71377f2769)