background content is %d characters, exceeding the hard limi

Error message

background content is %d characters, exceeding the hard limit of %d (aborting)

What it means

loadBackgroundFile counts the runes of the sanitized background content and enforces a hard limit of backgroundHardLimit (8000) characters, aborting the review when exceeded. A softer 2000-character limit only warns. The limit keeps the injected background from consuming too much of the LLM's context and degrading review quality.

Source

Thrown at cmd/opencodereview/background_file.go:102

	}

	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",
			path, backgroundOpenTag, backgroundCloseTag,
		)
	}

	// Enforce the limits on the cleaned content only: the wrapper delimiters add
	// overhead the user cannot control, so counting them would make the reported
	// character count misleading.
	if n := len([]rune(cleaned)); n > backgroundHardLimit {
		return "", fmt.Errorf(
			"background content is %d characters, exceeding the hard limit of %d (aborting)",
			n, backgroundHardLimit,
		)
	} else if n > backgroundSoftLimit {
		fmt.Fprintf(os.Stderr,
			"[ocr] --background-file content is %d characters, exceeding the recommended %d (continuing but review quality might be impacted)\n",
			n, backgroundSoftLimit,
		)
	}

	return backgroundOpenTag + "\n" + cleaned + "\n" + backgroundCloseTag, nil
}

func sanitizeMarkdown(s string) string {
	var b strings.Builder
	b.Grow(len(s))

	for _, r := range s {

View on GitHub (pinned to 5cf97d0d15)

Solutions

Trim the file to under 8000 characters, keeping only the most decision-relevant guidance.
Summarize the long document into a condensed bullet list (under the 2000-char soft limit for best quality).
Split content: keep only project-specific rules in --background-file; rely on the commit message fallback or --background for short notes.
Check `wc -m <path>` against the limit before running the review.

Example fix

// before: wc -m background.md -> 14500
// after
head -c important-sections.txt background.md  # manually curate
wc -m background.md  # -> 1800, under the soft limit

Defensive patterns

Strategy: validation

Validate before calling

// shell: check rune/char count against ocr's hard limit before invoking
chars=$(python3 -c "import sys;print(len(open(sys.argv[1],encoding='utf-8').read()))" "$BG_FILE")
[ "$chars" -le 8000 ] || { echo "background file too large: $chars chars"; exit 1; }

Try / catch

out, err := exec.Command("ocr", "review", "--background-file", bg).CombinedOutput()
if err != nil && strings.Contains(string(out), "exceeding the hard limit") {
	return fmt.Errorf("trim %s below 8000 characters: %w", bg, err)
}

Prevention

Keep background files concise; target under the 2000-character soft limit for best review quality.
Run `wc -m background.md` before reviews; CI can enforce a max.
Summarize long docs into bullet lists rather than pasting full documents.

When it happens

Trigger: `ocr review --background-file <path>` where the sanitized file contains more than 8000 characters (runes, not bytes).

Common situations: Dumping an entire architecture wiki page or coding standard document as background; concatenating multiple docs into one background file; a runaway export that pasted a whole codebase README plus design docs.

Related errors

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