alibaba/open-code-review · error

read background file %q: %w

Error message

read background file %q: %w

What it means

loadBackgroundFile fails to os.Stat the --background file and wraps the OS error. The path could not be read at all — most often it does not exist, but the wrapped error distinguishes permission and path-syntax issues too.

Source

Thrown at cmd/opencodereview/background_file.go:69

	if backgroundFile != "" {
		fileBg, err := loadBackgroundFile(resolveBackgroundFilePath(repoDir, backgroundFile))
		if err != nil {
			return "", err
		}
		return selectBackground(inline, fileBg), nil
	}
	if inline == "" && commit != "" {
		if msg, err := getCommitMessage(repoDir, commit); err == nil && msg != "" {
			return msg, nil
		}
	}
	return inline, nil
}

func loadBackgroundFile(path string) (string, error) {
	info, err := os.Stat(path)
	if err != nil {
		return "", fmt.Errorf("read background file %q: %w", path, err)
	}
	if info.IsDir() {
		return "", fmt.Errorf("background file %q is a directory, not a file", path)
	}
	if info.Size() > maxBackgroundFileBytes {
		return "", fmt.Errorf(
			"background file %q is %d bytes, exceeding the maximum of %d bytes; please provide a smaller file",
			path, info.Size(), maxBackgroundFileBytes,
		)
	}

	raw, err := os.ReadFile(path)
	if err != nil {
		return "", fmt.Errorf("read background file %q: %w", path, err)
	}

	cleaned := sanitizeMarkdown(string(raw))
	if cleaned == "" {

View on GitHub (pinned to 5cf97d0d15)

Solutions

1. Check the path is correct and relative to the directory you run ocr from (see TestLoadBackgroundFileRelativeToRepo — paths resolve against the repo).
2. Run ls <path> / os.Stat manually to see the underlying error (ENOENT vs EACCES).
3. Use an absolute path to eliminate CWD ambiguity.
4. Verify parent-directory read/execute permissions if the file itself looks fine.

Example fix

// before
ocr review --background ./notes.md   # run from home dir, notes.md is in repo
// after
cd /path/to/repo && ocr review --background ./notes.md
// or use an absolute path:
ocr review --background /path/to/repo/notes.md

const fs = require('fs');
const path = process.argv[2];
if (!fs.existsSync(path) || !fs.statSync(path).isFile()) {
  throw new Error(`background file not found: ${path} (resolve against your repo/CWD)`);
}

func isReadableFile(path string) bool {
    info, err := os.Stat(path)
    return err == nil && info.Mode().IsRegular()
}

bg, err := loadBackgroundFile(path)
if err != nil {
    return fmt.Errorf("loading --background: %w", err) // wraps the stat error for user display
}

When it happens

Trigger: Calling resolveBackground where the user-supplied background file path fails os.Stat: nonexistent file, wrong relative directory, typo, or no read permission on a parent directory.

Common situations: Relative path assuming repo root as CWD but running from elsewhere; file deleted or renamed; Windows vs Unix path separators in scripts; symlink to a missing target.

Related errors

• background file %q is a directory, not a file
• list sessions: %w
• get working directory: %w
• resolve absolute path: %w
• "%q %s" (+ positional signature, valid values, usage line, e

AI-assisted analysis of alibaba/open-code-review@5cf97d0d15 (2026-09-02). Data as JSON: /api/errors/582f71c55080473f. Report an issue: GitHub.