docling-project/docling · error · ValueError

Invalid Tesseract data path: contains null byte.

Error message

Invalid Tesseract data path: contains null byte.

What it means

The Tesseract data directory path (tessdata path) is passed to the Tesseract CLI, so Docling sanitizes it and explicitly rejects any value containing a NUL byte (\x00), which cannot be a legitimate path component and is a classic argument injection vector.

Solutions

1. Remove the null byte from the data path string (strip control characters before assigning the option).
2. Source the path from a validated configuration system rather than raw external input.
3. Verify with 'print(repr(value))' that the path you pass has no \x00 characters.

Example fix

# before
TesseractOcrOptions(data_path="/usr/share/tesseract-ocr/4.00/tessdata\x00")

# after
TesseractOcrOptions(data_path="/usr/share/tesseract-ocr/4.00/tessdata")

def safe_data_path(path: str) -> str:
    if "\x00" in path:
        raise ValueError("data path contains NUL byte")
    return path

ocr_options.data_path = safe_data_path(raw_config["tessdata_dir"])

def is_nul_free(s: str) -> bool:
    return "\x00" not in s

try:
    ocr_options.data_path = value
except ValueError as e:
    if "null byte" in str(e):
        log.warning("rejecting tessdata path with NUL byte")
        value = value.split("\x00")[0]  # only if recovery is acceptable
    else:
        raise

When it happens

Trigger: Setting the Tesseract data path option (e.g. TesseractOcrOptions(data_path=...) or the equivalent TESSDATA path option) to a string that embeds a null byte, usually from malformed user input or binary data decoded into the config.

Common situations: Config values read from binary/truncated files or untrusted HTTP payloads that carry control characters; defensive rejection before the path is resolved and forwarded to the CLI.

Related errors

• Invalid filename: contains null byte.
• Invalid Tesseract command: contains null byte.
• Invalid Tesseract language identifier
• invalid tesseract document orientation
• Archive exceeds maximum member count limit of

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/f82021f6c852fe80. Report an issue: GitHub.

Appendix: source

Thrown at docling/models/stages/ocr/tesseract_ocr_cli_model.py:112

        Valid identifiers (e.g. ``eng``, ``script/Latin``, ``eng+deu``) contain only
        alphanumeric characters, underscores, hyphens, forward slashes, and plus signs.
        """
        if not _VALID_LANG_RE.match(lang):
            raise ValueError(
                f"Invalid Tesseract language identifier: {lang!r}. "
                "Language identifiers must only contain alphanumeric characters, "
                "underscores, hyphens, forward slashes, and plus signs."
            )
        return lang

    @staticmethod
    def _sanitize_path(path: str) -> str:
        """Validate and sanitize a Tesseract data directory path to prevent argument injection.

        Rejects paths containing null bytes and resolves the path to an absolute form.
        """
        if "\x00" in path:
            raise ValueError("Invalid Tesseract data path: contains null byte.")
        return str(Path(path).resolve())

    @staticmethod
    def _sanitize_cmd(cmd: str) -> str:
        """Validate and sanitize the Tesseract executable name/path to prevent injection.

        Rejects values containing null bytes.
        """
        if "\x00" in cmd:
            raise ValueError("Invalid Tesseract command: contains null byte.")
        return cmd

    @staticmethod
    def _sanitize_filename(filename: str) -> str:
        """Validate and sanitize a filename passed to the Tesseract CLI.

        Rejects paths containing null bytes and resolves to an absolute path.
        """

View on GitHub (pinned to 61d76f1ff3)