What causes "background file %q is a directory, not a file" in alibaba/open-code-review?

Point --background at a single Markdown/text file inside that directory (e.g. ./docs/background.md).

background file %q is a directory, not a file

Error message

background file %q is a directory, not a file

What it means

loadBackgroundFile stat'ed the path successfully but info.IsDir() is true, so it rejects directories explicitly — the background must be a readable file of prose, not a directory. Fail-fast before attempting os.ReadFile which would return a confusing EISDIR error.

Source

Thrown at cmd/opencodereview/background_file.go:72

			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 == "" {
		return "", fmt.Errorf("background file %q is empty after sanitisation", path)
	}

View on GitHub (pinned to 5cf97d0d15)

Solutions

Point --background at a single Markdown/text file inside that directory (e.g. ./docs/background.md).
Concatenate the directory's files into one file first if you need folder-level background content.
Check the path for typos or a trailing component that makes it a directory (e.g. mkdir'd file name).
Use ls -la <path> to confirm it is a regular file, not a directory.

Example fix

// before
ocr review --background ./docs
// after
ocr review --background ./docs/project-context.md

Defensive patterns

Strategy: validation

Validate before calling

const fs = require('fs');
const st = fs.statSync(process.argv[2]);
if (st.isDirectory()) throw new Error('background must be a single file, not a directory');

Type guard

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

Try / catch

bg, err := loadBackgroundFile(path)
if err != nil && strings.Contains(err.Error(), "is a directory") {
    return fmt.Errorf("--background requires a file; concatenate the directory's files first")
}

Prevention

Pass a single Markdown/text file, never a directory — the feature does not concatenate folders
Watch shell completion: it happily fills in directories
Concatenate folder contents into one curated file beforehand
Sanity-check with test -f <path> in scripts before invoking ocr

When it happens

Trigger: Passing a directory path to the background file option, e.g. --background ./docs or --background . — a path that exists but resolves to a directory.

Common situations: Intending to load all files in a folder but supplying the folder itself; shell completion filling in a directory; a trailing-slash path that exists as a directory; expecting recursive directory concatenation which the feature does not support.

Related errors

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