{"record":{"id":"57c55dd6f7888959","repo":"gastownhall/beads","slug":"no-beads-directory-found-57c55d","errorCode":null,"errorMessage":"no .beads directory found","messagePattern":"no \\.beads directory found","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/beads/context.go","lineNumber":108,"sourceCode":"// 1. CWD doesn't change during command execution\n// 2. BEADS_DIR doesn't change during command execution\n// 3. Repeated filesystem access would be wasteful\n//\n// Returns an error if no .beads directory can be found.\nfunc GetRepoContext() (*RepoContext, error) {\n\trepoCtxOnce.Do(func() {\n\t\trepoCtx, repoCtxErr = buildRepoContext()\n\t})\n\treturn repoCtx, repoCtxErr\n}\n\n// buildRepoContext constructs the RepoContext by resolving all paths.\n// This is called once per process via sync.Once.\nfunc buildRepoContext() (*RepoContext, error) {\n\t// 1. Find .beads directory (respects BEADS_DIR env var)\n\tbeadsDir := FindBeadsDir()\n\tif beadsDir == \"\" {\n\t\treturn nil, fmt.Errorf(\"no .beads directory found\")\n\t}\n\n\t// 2. Security: Validate path boundary (SEC-003)\n\tif !isPathInSafeBoundary(beadsDir) {\n\t\treturn nil, fmt.Errorf(\"BEADS_DIR points to unsafe location: %s\", beadsDir)\n\t}\n\n\t// 3. Check for redirect file in the local repo\n\tredirectInfo := GetRedirectInfo()\n\n\t// 4. Determine RepoRoot based on external/redirect status\n\tvar repoRoot string\n\tisExternal := redirectInfo.IsRedirected\n\tif !isExternal {\n\t\tif external, err := isExternalBeadsDir(beadsDir); err == nil {\n\t\t\tisExternal = external\n\t\t}\n\t}","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/beads/context.go#L90-L126","documentation":"buildRepoContext resolves the repository context once per process via sync.Once; if FindBeadsDir() (which respects BEADS_DIR) cannot locate a .beads directory, it returns this error. GetRepoContext then returns it on every subsequent call because the failure is cached for the process lifetime. It means bd cannot find any beads workspace — from the CWD upward, via git root, or via BEADS_DIR.","triggerScenarios":"Running bd commands outside any repository that contains .beads/; a repo where .beads/ was never initialized (no `bd init`); BEADS_DIR set to a nonexistent or misspelled path; running from a directory outside the repo subtree with no discovery path to a .beads dir.","commonSituations":"Cloning a repo whose .beads/ directory was gitignored and never created; running bd in $HOME or a scratch directory; typos in BEADS_DIR; CI jobs checking out only a subdirectory.","solutions":["Run `bd init` (or `git init` + `bd init`) in the repository root to create .beads/.","cd into the repository that contains the .beads directory before running bd.","Fix or unset BEADS_DIR — verify the path exists and contains a .beads dir.","Check whether .beads/ was deleted or is missing after a fresh clone; restore or re-init it.","Since the failure is cached via sync.Once, restart the process after fixing the environment."],"exampleFix":"// before\nrc, err := beads.GetRepoContext() // \"no .beads directory found\" in fresh clone\n// after\nif _, statErr := os.Stat(\".beads\"); os.IsNotExist(statErr) {\n    return fmt.Errorf(\"run `bd init` first: %w\", err)\n}\nrc, err := beads.GetRepoContext()","handlingStrategy":"validation","validationCode":"if os.Getenv(\"BEADS_DIR\") == \"\" {\n    if _, err := os.Stat(\".beads\"); os.IsNotExist(err) {\n        return fmt.Errorf(\"no .beads directory here; run `bd init`\")\n    }\n}","typeGuard":null,"tryCatchPattern":"if _, err := beads.GetRepoContext(); err != nil {\n    if strings.Contains(err.Error(), \"no .beads directory found\") {\n        return fmt.Errorf(\"run `bd init` in your repository first: %w\", err)\n    }\n    return err\n}","preventionTips":["Run `bd init` in every repo before using bd commands.","cd into the repository root (or a subdirectory of it) before invoking bd.","Verify BEADS_DIR points to an existing .beads directory.","Restart processes after creating .beads — the lookup result is cached per process."],"tags":["go","setup","workspace","beads-init","environment"],"backgroundTag":"no-beads-directory","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}