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.

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)

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 Tesseract language identifier: {lang!r}. Language id
• Invalid Tesseract command: 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/f82021f6c852fe80. Report an issue: GitHub.