gastownhall/beads · error

no config.yaml found in BEADS_DIR (%s) (run 'bd init' first)

Error message

no config.yaml found in BEADS_DIR (%s) (run 'bd init' first)

What it means

findProjectConfigYamlWithFinder returns this error when BEADS_DIR is set but no config.yaml exists inside that directory. bd treats a configured BEADS_DIR as authoritative, so instead of falling back to project resolution it fails fast and tells the user to run 'bd init'. The %s is the BEADS_DIR value that was searched.

Source

Thrown at internal/config/yaml_config.go:586

//
// Resolution order:
//  1. BEADS_DIR/config.yaml (when BEADS_DIR is set)
//  2. Walk up from CWD to find .beads/config.yaml
//
// This keeps YAML-only config behavior aligned with runtime resolution when
// BEADS_DIR points to an external runtime directory.
func findProjectConfigYaml() (string, error) {
	return findProjectConfigYamlWithFinder(findProjectBeadsDir)
}

func findProjectConfigYamlWithFinder(findBeadsDir func() string) (string, error) {
	// Respect BEADS_DIR first when set.
	if beadsDir := os.Getenv("BEADS_DIR"); beadsDir != "" {
		configPath := filepath.Join(beadsDir, "config.yaml")
		if _, err := os.Stat(configPath); err == nil {
			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)")
}

View on GitHub (pinned to 71377f2769)

Solutions

1. Run 'bd init' with BEADS_DIR set to that directory so config.yaml is created there
2. Correct BEADS_DIR to the directory that actually holds your config.yaml
3. Unset BEADS_DIR to fall back to normal project config resolution
4. Copy or restore the missing config.yaml into the BEADS_DIR directory

Example fix

// before (fails)
export BEADS_DIR=/tmp/newdir
bd config set dolt.mode embedded  # no config.yaml found in BEADS_DIR (/tmp/newdir)
// after
export BEADS_DIR=/tmp/newdir
bd init
bd config set dolt.mode embedded

if dir := os.Getenv("BEADS_DIR"); dir != "" {
    if _, err := os.Stat(filepath.Join(dir, "config.yaml")); err != nil {
        return fmt.Errorf("BEADS_DIR=%s has no config.yaml; run 'bd init'", dir)
    }
}

func beadsDirInitialized(dir string) bool {
    _, err := os.Stat(filepath.Join(dir, "config.yaml"))
    return err == nil
}

if err := SetYamlConfig(key, value); err != nil {
    if strings.Contains(err.Error(), "no config.yaml found in BEADS_DIR") {
        // run bd init in BEADS_DIR or fix/unset BEADS_DIR, then retry
    }
    return err
}

When it happens

Trigger: Any YAML config write (Set/UnsetYamlConfig) or path resolution while the BEADS_DIR environment variable points to a directory that lacks a config.yaml file — typically a directory created manually or before 'bd init'.

Common situations: Exporting BEADS_DIR to a fresh/empty directory; typo'd BEADS_DIR path that exists but was never initialized; switching machines without copying config.yaml; running 'bd init' in a different directory than BEADS_DIR.

Related errors

• notion.data_source_id is not configured. Run 'bd notion init
• BEADS_DIR points to unsafe location: %s
• no .beads/config.yaml found (run 'bd init' first)
• server: NewDoltServer: doltBinExec is required
• server: NewDoltServer: rootDir is required

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