{"record":{"id":"5c7e39bcdada610a","repo":"gastownhall/beads","slug":"beads-directory-missing-required-files-s","errorCode":null,"errorMessage":"beads directory missing required files: %s","messagePattern":"beads directory missing required files: (.+?)","errorType":"exception","errorClass":null,"httpStatus":null,"severity":"error","filePath":"internal/beads/context.go","lineNumber":514,"sourceCode":"\t// 2. Find .beads directory in the appropriate location\n\tbeadsDir := filepath.Join(repoRoot, \".beads\")\n\n\t// Check if .beads exists\n\tif _, err := os.Stat(beadsDir); os.IsNotExist(err) {\n\t\treturn nil, fmt.Errorf(\"no .beads directory found at %s\", beadsDir)\n\t}\n\n\t// 3. Follow redirect if present\n\tbeadsDir = FollowRedirect(beadsDir)\n\n\t// 4. Security: Validate path boundary (SEC-003)\n\tif !isPathInSafeBoundary(beadsDir) {\n\t\treturn nil, fmt.Errorf(\"beads directory in unsafe location: %s\", beadsDir)\n\t}\n\n\t// 5. Validate directory contains actual project files\n\tif !hasBeadsProjectFiles(beadsDir) {\n\t\treturn nil, fmt.Errorf(\"beads directory missing required files: %s\", beadsDir)\n\t}\n\n\t// 6. Get CWD's repo root (same as workspace in this case)\n\tcwdRepoRoot := git.GetRepoRoot()\n\n\treturn &RepoContext{\n\t\tBeadsDir:     beadsDir,\n\t\tRepoRoot:     repoRoot,\n\t\tCWDRepoRoot:  cwdRepoRoot,\n\t\tIsRedirected: false, // Workspace-specific context is never \"redirected\"\n\t\tIsWorktree:   isWorktree,\n\t}, nil\n}\n\n// Validate checks if the cached context is still valid.\n//\n// Returns an error if BeadsDir or RepoRoot no longer exist. This is useful\n// for long-running processes that need to detect when context becomes stale (DMN-002).","sourceCodeStart":496,"sourceCodeEnd":532,"githubUrl":"https://github.com/gastownhall/beads/blob/71377f276968b452ee607177637970a4ff888584/internal/beads/context.go#L496-L532","documentation":"bd refuses to treat a directory as a beads workspace when the .beads directory does not contain the files that identify a real beads project (e.g. the database and metadata files). buildRepoContextForWorkspace validates the discovered beads directory and returns this error to stop callers from building a RepoContext against an empty or mis-created directory. It protects against stale or accidentally-created .beads folders.","triggerScenarios":"Calling GetRepoContextForWorkspace when the resolved beadsDir passes the safe-boundary check but hasBeadsProjectFiles(beadsDir) returns false — i.e. the directory exists but lacks the expected beads project files (empty .beads dir, directory containing only unrelated files, or a partially deleted/interrupted bd init).","commonSituations":"Manually creating a .beads directory without running bd init; a previous bd init that failed midway; a cleanup script deleting database files but leaving the directory; mounting an empty volume at the expected .beads path; pointing bd at a directory that only looks like a beads workspace.","solutions":["Run `bd init` inside the repository to (re)create the required .beads project files","Check the contents of the reported directory (`ls <dir>`) and restore any missing beads files from backup or re-sync (`bd dolt pull`)","If the directory is stale/empty and not needed, remove it and re-initialize","Verify you are in the intended repository — an upstream .beads directory elsewhere may be the one being resolved"],"exampleFix":"// before (manually created, empty)\nmkdir .beads\n// after\nbd init\n","handlingStrategy":"validation","validationCode":"func hasBeadsProject(dir string) bool {\n    entries, err := os.ReadDir(dir)\n    if err != nil { return false }\n    return len(entries) > 0 // then run bd init if empty\n}","typeGuard":null,"tryCatchPattern":"ctx, err := beads.GetRepoContextForWorkspace(cwd)\nif err != nil && strings.Contains(err.Error(), \"missing required files\") {\n    // run `bd init` then retry\n}","preventionTips":["Always initialize via `bd init`, never mkdir .beads by hand","Verify `ls .beads` shows database/metadata files before relying on the workspace","Restore deleted beads files promptly or re-sync instead of leaving an empty dir","Check bd output for the workspace it resolved to when nested repos exist"],"tags":["beads","workspace","validation","filesystem"],"backgroundTag":"beads-directory-incomplete","analyzedSha":"71377f276968b452ee607177637970a4ff888584","analyzedAt":"2026-08-30T18:55:39.744Z","schemaVersion":2},"datasetVersion":"2026-08-30T23:17:21.991Z"}