alibaba/open-code-review · error

background file %q is empty after sanitisation

Error message

background file %q is empty after sanitisation

What it means

loadBackgroundFile reads the file passed via --background-file, strips control/invisible characters with sanitizeMarkdown, and wraps the result in reserved delimiters. This error means the file existed and was read, but after sanitisation nothing printable remained — the content was entirely whitespace, control characters, or zero-width runes. The tool refuses to inject an empty background block into the review prompt.

Source

Thrown at cmd/opencodereview/background_file.go:88

	}
	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",
			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 {

View on GitHub (pinned to 5cf97d0d15)

Solutions

  1. Open the file and verify it contains real text (`cat -v <path>` or `hexdump -C <path>` shows the raw bytes).
  2. Remove BOM and invisible characters: `sed -i '1s/^\xEF\xBB\xBF//' <path>` or re-save as UTF-8 without BOM.
  3. If the file is intentionally a placeholder, put actual background prose in it (e.g. team conventions, architecture notes).
  4. Alternatively pass the background inline via `--background "..."` instead of a file.

Example fix

// before (hexdump: ef bb bf only — BOM, no text)
// after
printf 'Review with attention to error handling and concurrency.' > background.md
ocr review --background-file background.md
Defensive patterns

Strategy: validation

Validate before calling

// Go: preflight the background file before invoking ocr
raw, _ := os.ReadFile(path)
clean := sanitizeLikeOcr(string(raw)) // strip control/Cf chars, collapse newlines, trim
if clean == "" { return fmt.Errorf("%s has no usable content after sanitization", path) }

Type guard

func hasVisibleContent(b []byte) bool {
	for _, r := range string(b) {
		if r > 0x20 && r != 0x7F && !unicode.Is(unicode.Cf, r) {
			return true
		}
	}
	return false
}

Try / catch

out, err := exec.Command("ocr", "review", "--background-file", path, ...).CombinedOutput()
if err != nil && strings.Contains(string(out), "is empty after sanitisation") {
	// fall back to inline background or abort with a clear message
}

Prevention

When it happens

Trigger: Running `ocr review --background-file <path>` where the file's bytes are all stripped by sanitizeMarkdown: only C0/C1 control chars (0x00-0x1F, 0x7F-0x9F), Unicode Cf characters (BOM, zero-width space U+200B, soft hyphen), or whitespace-only text.

Common situations: A file exported with a UTF-8 BOM only; a placeholder file containing just newlines or tabs; a file whose text was accidentally deleted leaving invisible characters; a copied empty template; content lost after a failed editor save.

Related errors

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