What causes "cannot use -C directory %q: no beads project found" in gastownhall/beads?

Run `bd init` inside the target directory (or at its repo root) to create a beads project first

cannot use -C directory %q: no beads project found

Error message

cannot use -C directory %q: no beads project found

What it means

bd refuses a `-C <dir>` (change-directory) flag when the target directory is not inside a beads project. After confirming the path exists and is a directory, it calls beads.FindBeadsDirFrom to locate a `.beads` project rooted at or above the path; if none is found, it returns this error instead of proceeding. It exists to stop users from operating bd against a directory with no issue database.

Source

Thrown at cmd/bd/main.go:813

func resolveChangeDirBeadsDir(path string) (string, error) {
	if strings.TrimSpace(path) == "" {
		return "", nil
	}
	absPath, err := filepath.Abs(path)
	if err != nil {
		return "", fmt.Errorf("cannot resolve -C directory %q: %w", path, err)
	}
	info, err := os.Stat(absPath)
	if err != nil {
		return "", fmt.Errorf("cannot use -C directory %q: %w", path, err)
	}
	if !info.IsDir() {
		return "", fmt.Errorf("cannot use -C directory %q: not a directory", path)
	}
	beadsDir := beads.FindBeadsDirFrom(absPath)
	if beadsDir == "" {
		return "", fmt.Errorf("cannot use -C directory %q: no beads project found", path)
	}
	return beadsDir, nil
}

func applyChangeDirSelection() error {
	if strings.TrimSpace(changeDir) == "" {
		return nil
	}
	beadsDir, err := resolveChangeDirBeadsDir(changeDir)
	if err != nil {
		return HandleError("%v", err)
	}
	changeDirEnvSnapshot = make(map[string]envSnapshotValue, 3)
	for _, key := range []string{"BEADS_DIR", "BEADS_DB", "BD_DB"} {
		value, ok := os.LookupEnv(key)
		changeDirEnvSnapshot[key] = envSnapshotValue{value: value, ok: ok}
	}
	_ = os.Setenv("BEADS_DIR", beadsDir)

View on GitHub (pinned to 71377f2769)

Solutions

Run `bd init` inside the target directory (or at its repo root) to create a beads project first
Verify the path with `ls -a <dir>/.beads` — point -C at the repo root that actually contains .beads
Drop the -C flag and cd into the project directory instead
Check for typos in the directory path

Example fix

// before
bd -C /tmp/empty-dir list
// after
bd -C /home/me/myrepo list   # myrepo contains .beads/ from bd init

Defensive patterns

Strategy: validation

Validate before calling

func hasBeadsProject(dir string) bool {
	d := dir
	for {
		if fi, err := os.Stat(filepath.Join(d, ".beads")); err == nil && fi.IsDir() {
			return true
		}
		parent := filepath.Dir(d)
		if parent == d {
			return false
		}
		d = parent
	}
}
// call before: if !hasBeadsProject(dir) { bdInitOrFixPath(dir) }

Prevention

Always run bd init in a repo before using -C against it
Point -C at the repository root, not arbitrary subdirectories
Script a check for .beads/ existence before invoking bd with -C

When it happens

Trigger: Running `bd -C /some/path <command>` where /some/path exists and is a directory but contains no `.beads` directory (nor any ancestor one), so FindBeadsDirFrom returns "".

Common situations: Typo in the project path; pointing -C at a freshly created empty directory; running -C before `bd init` in that repo; pointing at a subdirectory outside the beads repo; CI scripts assuming a project exists.

Related errors

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