gastownhall/beads · error

cannot use -C directory %q: %w

Error message

cannot use -C directory %q: %w

What it means

resolveChangeDirBeadsDir stats the resolved -C path; if os.Stat fails (path does not exist, permission denied, or a broken symlink), bd rejects the flag with 'cannot use -C directory' wrapping the OS error.

Source

Thrown at cmd/bd/main.go:806

	rootCmd.AddGroup(&cobra.Group{ID: "maint", Title: "Maintenance:"})
	rootCmd.AddGroup(&cobra.Group{ID: "advanced", Title: "Integrations & Advanced:"})

	// Custom help function with semantic coloring (Tufte-inspired)
	// Note: Usage output (shown on errors) is not styled to avoid recursion issues
	rootCmd.SetHelpFunc(colorizedHelpFunc)
}

func resolveChangeDirBeadsDir(path string) (string, error) {
	if strings.TrimSpace(path) == "" {
		return "", nil
	}
	absPath, err := filepath.Abs(path)
	if err != nil {
		return "", fmt.Errorf("cannot resolve -C directory %q: %w", path, err)
	}
	info, err := os.Stat(absPath)
	if err != nil {
		return "", fmt.Errorf("cannot use -C directory %q: %w", path, err)
	}
	if !info.IsDir() {
		return "", fmt.Errorf("cannot use -C directory %q: not a directory", path)
	}
	beadsDir := beads.FindBeadsDirFrom(absPath)
	if beadsDir == "" {
		return "", fmt.Errorf("cannot use -C directory %q: no beads project found", path)
	}
	return beadsDir, nil
}

func applyChangeDirSelection() error {
	if strings.TrimSpace(changeDir) == "" {
		return nil
	}
	beadsDir, err := resolveChangeDirBeadsDir(changeDir)
	if err != nil {
		return HandleError("%v", err)

View on GitHub (pinned to 71377f2769)

Solutions

1. Verify the path exists: ls <path>
2. Check for typos and that you are invoking from the expected cwd
3. Fix permissions or use a path you can access
4. Remove or repair broken symlinks

Example fix

// before
bd -C ./projcts bd list   # typo, dir doesn't exist
// after
ls ./projects             # confirm it exists
bd -C ./projects bd list

info, err := os.Stat(dirFlag)
if err != nil || !info.IsDir() {
    return fmt.Errorf("-C must be an existing directory: %s", dirFlag)
}

When it happens

Trigger: `bd -C <path> <command>` where the path does not exist, the user lacks traverse permissions, or the path is a dangling symlink; also fires before the not-a-directory check whenever Stat errors.

Common situations: Typo in the -C path; running from a different cwd than expected in scripts; deleted or renamed project directory; permission issues in containers/CI.

Related errors

• cannot resolve -C directory %q: %w
• cannot use -C directory %q: not a directory
• reading reason file %q: %w
• target repo %s is not initialized; refusing to initialize it
• failed to inspect target repo %s: %w

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