docling-project/docling · error · ValueError

Invalid Tesseract command: contains null byte.

Error message

Invalid Tesseract command: contains null byte.

What it means

The tesseract_cmd option (name or path of the tesseract executable) is validated before being used to spawn the CLI process. A value containing a NUL byte is rejected with this ValueError, because NUL bytes cannot appear in real executable paths and indicate malformed or malicious input.

Source

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

    @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.
        """
        if "\x00" in filename:
            raise ValueError("Invalid filename: contains null byte.")
        return str(Path(filename).resolve())

    def _get_name_and_version(self) -> Tuple[str, str]:
        if self._name is not None and self._version is not None:
            return self._name, self._version  # type: ignore

        cmd = [self._safe_tesseract_cmd, "--version"]

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Set tesseract_cmd to a clean executable name or absolute path, e.g. 'tesseract' or '/usr/bin/tesseract'.
2. Strip control characters from any externally sourced value before assigning it to tesseract_cmd.
3. Confirm with repr() that the value contains no \x00.

Example fix

# before
ocr_options.tesseract_cmd = "tesseract\x00"

# after
ocr_options.tesseract_cmd = "/usr/bin/tesseract"

def safe_cmd(cmd: str) -> str:
    if "\x00" in cmd:
        raise ValueError("tesseract_cmd contains NUL byte")
    return cmd

ocr_options.tesseract_cmd = safe_cmd(settings["tesseract_cmd"])

def is_nul_free_cmd(cmd: str) -> bool:
    return "\x00" not in cmd and bool(cmd.strip())

try:
    TesseractOcrCliModel(options=opts)
except ValueError as e:
    if "Invalid Tesseract command" in str(e):
        opts.tesseract_cmd = "tesseract"  # reset to default binary
    else:
        raise

When it happens

Trigger: Setting pipeline_options.ocr_options.tesseract_cmd to a string containing \x00, typically from unsanitized configuration or user-supplied settings.

Common situations: Config strings sourced from untrusted input or from decodes of binary data; rarely a hand-typed mistake, more often an injection probe against the subprocess call.

Related errors

• Invalid Tesseract language identifier: {lang!r}. Language id
• Invalid Tesseract data path: contains null byte.
• Invalid filename: contains null byte.
• invalid tesseract document orientation {orientation}, expect
• Archive exceeds maximum member count limit of {self.options.

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