gastownhall/beads · error

cannot use -C directory %q: not a directory

Error message

cannot use -C directory %q: not a directory

What it means

After confirming the -C path exists via os.Stat, bd requires it to be a directory (not a regular file, device, etc.). Passing a file path triggers this explicit 'not a directory' error with no wrapped OS error.

Source

Thrown at cmd/bd/main.go:809

	// 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)
	}
	changeDirEnvSnapshot = make(map[string]envSnapshotValue, 3)
	for _, key := range []string{"BEADS_DIR", "BEADS_DB", "BD_DB"} {

View on GitHub (pinned to 71377f2769)

Solutions

1. Pass the project (or .beads) directory, not a file: `bd -C ./myrepo ...`
2. Fix the script/completion that expanded to a file path
3. Use the repository root as the -C value

Example fix

// before
bd -C .beads/config.json bd list   # a file
// after
bd -C . bd list                     # a directory

info, err := os.Stat(dirFlag)
if err == nil && !info.IsDir() {
    return fmt.Errorf("-C points at a file, need a directory: %s", dirFlag)
}

When it happens

Trigger: `bd -C <path>` where <path> resolves to a regular file (e.g. pointing at .beads/issues.jsonl or config.json instead of the project directory).

Common situations: Pointing -C at a file inside the project instead of the project root; shell completion or scripts accidentally expanding to a filename; confusion between the beads dir and its files.

Related errors

• cannot resolve -C directory %q: %w
• cannot use -C directory %q: %w
• 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/d40830bd8d7e101f. Report an issue: GitHub.