gastownhall/beads · error

cannot resolve -C directory %q: %w

Error message

cannot resolve -C directory %q: %w

What it means

When the -C flag is given, bd resolves the provided path to an absolute directory to locate the beads project. If filepath.Abs itself fails (rare OS-level path resolution error), the path cannot be resolved and this wrapped error is returned before any filesystem probing.

Source

Thrown at cmd/bd/main.go:802

	rootCmd.AddGroup(&cobra.Group{ID: "setup", Title: "Setup & Configuration:"})
	// NOTE: Many maintenance commands (clean, cleanup, compact, validate, repair-deps)
	// should eventually be consolidated into 'bd doctor' and 'bd doctor --fix' to simplify
	// the user experience. The doctor command can detect issues and offer fixes interactively.
	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

View on GitHub (pinned to 71377f2769)

Solutions

1. Re-run with a simpler/shorter relative path (e.g. cd closer to the project first)
2. Check the path for invalid characters
3. Verify OS path-length limits and shorten the directory chain if needed

Example fix

// before
bd -C /very/long/path/.../repo bd list
// after
cd /very/long/path/.../repo
bd list   # or use a shorter -C path

if _, err := filepath.Abs(dirFlag); err != nil {
    return fmt.Errorf("invalid -C path: %w", err)
}

When it happens

Trigger: Passing a -C value whose absolute-path resolution fails — typically only with pathological paths (e.g. extremely long paths exceeding OS limits on some systems) or platform-specific path errors.

Common situations: Very long path components on Linux; malformed path bytes; embedded NUL or invalid characters in the path argument from scripted invocation.

Related errors

• cannot use -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/f2087fbbf30596de. Report an issue: GitHub.