gastownhall/beads · error

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.

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)

Solutions

1. Run 'bd init' in the project root to create .beads/config.yaml
2. cd into the repository/project that contains .beads/config.yaml before running config commands
3. If the config lives elsewhere, set BEADS_DIR to the directory containing config.yaml
4. 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

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'")
    }
}

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

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
}

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

• notion.data_source_id is not configured. Run 'bd notion init
• no config.yaml found in BEADS_DIR (%s) (run 'bd init' first)
• server: NewDoltServer: doltBinExec is required
• server: NewDoltServer: rootDir is required
• server: NewDoltServer: configPath is required

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