{"record":{"id":"f5d4081cfac9870b","repo":"gastownhall/beads","slug":"cannot-use-c-directory-q-no-beads-project-found","errorCode":null,"errorMessage":"cannot use -C directory %q: no beads project found","messagePattern":"cannot use -C directory %q: no beads project found","errorType":"validation","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/main.go","lineNumber":813,"sourceCode":"\nfunc resolveChangeDirBeadsDir(path string) (string, error) {\n\tif strings.TrimSpace(path) == \"\" {\n\t\treturn \"\", nil\n\t}\n\tabsPath, err := filepath.Abs(path)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"cannot resolve -C directory %q: %w\", path, err)\n\t}\n\tinfo, err := os.Stat(absPath)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"cannot use -C directory %q: %w\", path, err)\n\t}\n\tif !info.IsDir() {\n\t\treturn \"\", fmt.Errorf(\"cannot use -C directory %q: not a directory\", path)\n\t}\n\tbeadsDir := beads.FindBeadsDirFrom(absPath)\n\tif beadsDir == \"\" {\n\t\treturn \"\", fmt.Errorf(\"cannot use -C directory %q: no beads project found\", path)\n\t}\n\treturn beadsDir, nil\n}\n\nfunc applyChangeDirSelection() error {\n\tif strings.TrimSpace(changeDir) == \"\" {\n\t\treturn nil\n\t}\n\tbeadsDir, err := resolveChangeDirBeadsDir(changeDir)\n\tif err != nil {\n\t\treturn HandleError(\"%v\", err)\n\t}\n\tchangeDirEnvSnapshot = make(map[string]envSnapshotValue, 3)\n\tfor _, key := range []string{\"BEADS_DIR\", \"BEADS_DB\", \"BD_DB\"} {\n\t\tvalue, ok := os.LookupEnv(key)\n\t\tchangeDirEnvSnapshot[key] = envSnapshotValue{value: value, ok: ok}\n\t}\n\t_ = os.Setenv(\"BEADS_DIR\", beadsDir)","sourceCodeStart":795,"sourceCodeEnd":831,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/main.go#L795-L831","documentation":"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.","triggerScenarios":"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 \"\".","commonSituations":"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.","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"],"exampleFix":"// before\nbd -C /tmp/empty-dir list\n// after\nbd -C /home/me/myrepo list   # myrepo contains .beads/ from bd init","handlingStrategy":"validation","validationCode":"func hasBeadsProject(dir string) bool {\n\td := dir\n\tfor {\n\t\tif fi, err := os.Stat(filepath.Join(d, \".beads\")); err == nil && fi.IsDir() {\n\t\t\treturn true\n\t\t}\n\t\tparent := filepath.Dir(d)\n\t\tif parent == d {\n\t\t\treturn false\n\t\t}\n\t\td = parent\n\t}\n}\n// call before: if !hasBeadsProject(dir) { bdInitOrFixPath(dir) }","typeGuard":null,"tryCatchPattern":null,"preventionTips":["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"],"tags":["cli","configuration","missing-project"],"backgroundTag":"no-beads-project-found","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}