gastownhall/beads · error

beads directory missing required files: %s

Error message

beads directory missing required files: %s

What it means

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.

Source

Thrown at internal/beads/context.go:514

	// 2. Find .beads directory in the appropriate location
	beadsDir := filepath.Join(repoRoot, ".beads")

	// Check if .beads exists
	if _, err := os.Stat(beadsDir); os.IsNotExist(err) {
		return nil, fmt.Errorf("no .beads directory found at %s", beadsDir)
	}

	// 3. Follow redirect if present
	beadsDir = FollowRedirect(beadsDir)

	// 4. Security: Validate path boundary (SEC-003)
	if !isPathInSafeBoundary(beadsDir) {
		return nil, fmt.Errorf("beads directory in unsafe location: %s", beadsDir)
	}

	// 5. Validate directory contains actual project files
	if !hasBeadsProjectFiles(beadsDir) {
		return nil, fmt.Errorf("beads directory missing required files: %s", beadsDir)
	}

	// 6. Get CWD's repo root (same as workspace in this case)
	cwdRepoRoot := git.GetRepoRoot()

	return &RepoContext{
		BeadsDir:     beadsDir,
		RepoRoot:     repoRoot,
		CWDRepoRoot:  cwdRepoRoot,
		IsRedirected: false, // Workspace-specific context is never "redirected"
		IsWorktree:   isWorktree,
	}, nil
}

// Validate checks if the cached context is still valid.
//
// Returns an error if BeadsDir or RepoRoot no longer exist. This is useful
// for long-running processes that need to detect when context becomes stale (DMN-002).

View on GitHub (pinned to 71377f2769)

Solutions

1. Run `bd init` inside the repository to (re)create the required .beads project files
2. Check the contents of the reported directory (`ls <dir>`) and restore any missing beads files from backup or re-sync (`bd dolt pull`)
3. If the directory is stale/empty and not needed, remove it and re-initialize
4. Verify you are in the intended repository — an upstream .beads directory elsewhere may be the one being resolved

Example fix

// before (manually created, empty)
mkdir .beads
// after
bd init

func hasBeadsProject(dir string) bool {
    entries, err := os.ReadDir(dir)
    if err != nil { return false }
    return len(entries) > 0 // then run bd init if empty
}

ctx, err := beads.GetRepoContextForWorkspace(cwd)
if err != nil && strings.Contains(err.Error(), "missing required files") {
    // run `bd init` then retry
}

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• invalid path: %w
• not a beads workspace: .beads directory not found for %s
• remote target %s is non-empty but is neither a bare git repo
• graph dependency cycle would be created: %s
• path is a directory, not a file

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