gastownhall/beads · error

no .beads/config.yaml found in current directory or parents

Error message

no .beads/config.yaml found in current directory or parents

What it means

FindConfigYAMLPath walks up from the current working directory looking for .beads/config.yaml and returns this error when no such file exists anywhere in the ancestor chain. It means the command was run outside any initialized beads project.

Source

Thrown at internal/config/repos.go:28

// ReposConfig represents the repos section of config.yaml
type ReposConfig struct {
	Primary    string   `yaml:"primary,omitempty"`
	Additional []string `yaml:"additional,omitempty,flow"`
}

// configFile represents the structure for reading/writing config.yaml
// We use yaml.Node to preserve comments and formatting
type configFile struct {
	root yaml.Node
}

// FindConfigYAMLPath finds the config.yaml file in .beads directory
// Walks up from CWD to find .beads/config.yaml
func FindConfigYAMLPath() (string, error) {
	configPath, err := findProjectConfigYaml()
	if err != nil {
		return "", fmt.Errorf("no .beads/config.yaml found in current directory or parents")
	}
	return configPath, nil
}

// GetReposFromYAML reads the repos configuration from config.yaml
// Returns an empty ReposConfig if repos section doesn't exist
func GetReposFromYAML(configPath string) (*ReposConfig, error) {
	data, err := os.ReadFile(configPath) // #nosec G304 - config file path from caller
	if err != nil {
		if os.IsNotExist(err) {
			return &ReposConfig{}, nil
		}
		return nil, fmt.Errorf("failed to read config.yaml: %w", err)
	}

	// Parse into a generic map to extract repos section
	var cfg map[string]interface{}
	if err := yaml.Unmarshal(data, &cfg); err != nil {

View on GitHub (pinned to 71377f2769)

Solutions

1. Run `bd init` in the project root to create .beads/config.yaml.
2. cd into the project directory (or a subdirectory of it) before running the command.
3. Verify .beads/config.yaml exists and wasn't deleted or excluded by your ignore/clean rules.

Example fix

// before: command run in ~/random-dir
// after
$ cd /path/to/my-project
$ bd init
$ bd repo add ../other-repo

if _, err := os.Stat(filepath.Join(".beads", "config.yaml")); os.IsNotExist(err) {
    return fmt.Errorf("not in a beads project; run `bd init` first")
}

path, err := config.FindConfigYAMLPath()
if err != nil {
    return fmt.Errorf("no beads project here: %w (run `bd init`)", err)
}

When it happens

Trigger: Calling FindConfigYAMLPath() (used by AddRepo/RemoveRepo/ListRepos flows) while the CWD — or any parent — lacks a .beads/config.yaml; running from a freshly cloned repo before `bd init`; running from a subdirectory outside the project tree (e.g. $HOME).

Common situations: Forgetting to run `bd init` in a new repository; running the CLI from the wrong terminal tab/directory; the .beads directory was deleted or gitignored out of existence; working in a worktree whose fallback to the main repo config is broken.

Related errors

• persist sync.remote to config.yaml: %w
• failed to persist sync.remote to config.yaml: %w
• failed to persist sync.remote to config.yaml: %v
• failed to configure hydration: %w
• error reading config file: %w

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