{"record":{"id":"6e14f82f6784b30b","repo":"gastownhall/beads","slug":"not-a-beads-workspace-beads-directory-not-found","errorCode":null,"errorMessage":"not a beads workspace: .beads directory not found for %s","messagePattern":"not a beads workspace: \\.beads directory not found for (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"cmd/bd/doctor/fix/common.go","lineNumber":78,"sourceCode":"// attempting any fix operations. This prevents path traversal attacks.\nfunc validateBeadsWorkspace(path string) error {\n\t_, err := resolveWorkspaceBeadsDirs(path)\n\treturn err\n}\n\nfunc resolveWorkspaceBeadsDirs(path string) (workspaceBeadsDirs, error) {\n\tabsPath, err := filepath.Abs(path)\n\tif err != nil {\n\t\treturn workspaceBeadsDirs{}, fmt.Errorf(\"invalid path: %w\", err)\n\t}\n\n\tdirs := workspaceBeadsDirs{\n\t\tlocal:    filepath.Join(absPath, \".beads\"),\n\t\tresolved: beads.ResolveBeadsDirForRepo(absPath),\n\t}\n\n\tif info, err := os.Stat(dirs.resolved); err != nil || !info.IsDir() {\n\t\treturn workspaceBeadsDirs{}, fmt.Errorf(\"not a beads workspace: .beads directory not found for %s\", absPath)\n\t}\n\n\treturn dirs, nil\n}\n\nfunc resolvedWorkspaceBeadsDir(path string) (string, error) {\n\tdirs, err := resolveWorkspaceBeadsDirs(path)\n\tif err != nil {\n\t\treturn \"\", err\n\t}\n\n\treturn dirs.resolved, nil\n}\n\nfunc localWorkspaceBeadsDir(path string) (string, error) {\n\tabsPath, err := filepath.Abs(path)\n\tif err != nil {\n\t\treturn \"\", fmt.Errorf(\"invalid path: %w\", err)","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/cmd/bd/doctor/fix/common.go#L60-L96","documentation":"After resolving the workspace's beads directory (via beads.ResolveBeadsDirForRepo), resolveWorkspaceBeadsDirs stats it and requires it to be an existing directory. If .beads is missing or is not a directory, this error declares the path is not a beads workspace and callers like validateBeadsWorkspace and Permissions refuse to operate.","triggerScenarios":"os.Stat(resolved) fails or returns a non-directory in resolveWorkspaceBeadsDirs (cmd/bd/doctor/fix/common.go:78) — running doctor fix commands outside any initialized bd repo, or a .beads path that is a file/symlink target that vanished.","commonSituations":"Running `bd doctor` fix subcommands in a repo where `bd init` was never run; wrong repo root passed (parent directory instead of the workspace); .beads accidentally deleted or replaced by a file; submodule/monorepo layouts where beads dir resolution picks a parent without .beads.","solutions":["Initialize the workspace: run `bd init` in the repo root to create .beads.","Verify you are passing the correct workspace root (the directory containing .beads).","Check that the resolved .beads path exists and is a directory: `ls -la <repo>/.beads`.","Restore .beads from backup or re-import from .beads/issues.jsonl if it was deleted."],"exampleFix":"// before\nfix.Permissions(\"/home/me/not-a-repo\")  // not a beads workspace\n// after\nbd init /home/me/repo                    // creates .beads\nfix.Permissions(\"/home/me/repo\")","handlingStrategy":"validation","validationCode":"resolved := beads.ResolveBeadsDirForRepo(repoRoot)\nif fi, err := os.Stat(resolved); err != nil || !fi.IsDir() {\n\t// run `bd init` in repoRoot before calling doctor fixes\n}","typeGuard":null,"tryCatchPattern":"if err := fix.Permissions(path); err != nil && strings.Contains(err.Error(), \"not a beads workspace\") {\n\t// initialize the workspace, then retry\n\treturn fmt.Errorf(\"run `bd init` in %s: %w\", path, err)\n}","preventionTips":["Run `bd init` in every repo before using doctor fix subcommands","Pass the repo root that actually contains .beads, not a parent","Don't delete or overwrite .beads; keep it under version-synced backup","In monorepos, confirm which directory beads treats as the workspace root"],"tags":["workspace","doctor","beads-dir","validation"],"backgroundTag":"not-a-beads-workspace","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}