alibaba/open-code-review · error

background file %q is %d bytes, exceeding the maximum of %d

Error message

background file %q is %d bytes, exceeding the maximum of %d bytes; please provide a smaller file

What it means

loadBackgroundFile rejects files larger than maxBackgroundFileBytes, reporting the actual size and the cap. The background text is injected into the LLM prompt, so oversized files would blow the token budget; a smaller file is requested explicitly.

Source

Thrown at cmd/opencodereview/background_file.go:75

	}
	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)
	}

	if strings.Contains(cleaned, backgroundOpenTag) || strings.Contains(cleaned, backgroundCloseTag) {
		return "", fmt.Errorf(
			"background file %q must not contain the reserved delimiters %q or %q",

View on GitHub (pinned to 5cf97d0d15)

Solutions

1. Trim the file to the essentials — background should be short project context, not a full corpus.
2. Split into a small curated summary file and pass that instead.
3. Check the file size (du -h <path>) against maxBackgroundFileBytes and compress the content (remove code blocks, history, boilerplate).
4. If the feature genuinely needs a bigger cap, build with a raised maxBackgroundFileBytes constant — but prefer summarizing.

Example fix

// before
ocr review --background ./full-architecture-docs.md   # 2 MB
// after
ocr review --background ./docs/summary.md   # curated < maxBackgroundFileBytes

const fs = require('fs');
const MAX = 512 * 1024; // match maxBackgroundFileBytes
const st = fs.statSync(path);
if (st.size > MAX) throw new Error(`background file is ${st.size} bytes; cap is ${MAX}`);

func fitsBackgroundLimit(path string, max int64) bool {
    info, err := os.Stat(path)
    return err == nil && !info.IsDir() && info.Size() <= max
}

When it happens

Trigger: Passing a background file whose os.Stat size exceeds maxBackgroundFileBytes to resolveBackground — e.g. a whole book-sized markdown document or a concatenated corpus.

Common situations: Dumping entire logs, generated docs, or a large wiki export as background; concatenating many files into one background document; raising the limit unknowingly via a huge auto-generated changelog.

Related errors

• background file %q is a directory, not a file
• invalid scan template: %w
• %w (run 'ocr session list' to see available sessions)
• sessions belong to different repositories: %s was recorded i
• --max-tokens must be a non-negative integer

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