docling-project/docling · error · ValueError

Invalid Tesseract language identifier: {lang!r}. Language id

Error message

Invalid Tesseract language identifier: {lang!r}. Language identifiers must only contain alphanumeric characters, underscores, hyphens, forward slashes, and plus signs.

What it means

Before passing language tokens to the Tesseract CLI, Docling validates each one against _VALID_LANG_RE (alphanumerics, underscores, hyphens, forward slashes, plus signs — e.g. 'eng', 'script/Latin', 'eng+deu'). Any character outside that set raises this ValueError; this guard prevents argument injection into the tesseract command line.

Source

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

                self._set_languages_and_prefix()

            except Exception as exc:
                raise RuntimeError(
                    f"Tesseract is not available, aborting: {exc} "
                    "Install tesseract on your system and the tesseract binary is discoverable. "
                    "The actual command for Tesseract can be specified in `pipeline_options.ocr_options.tesseract_cmd='tesseract'`. "
                    "Alternatively, Docling has support for other OCR engines. See the documentation."
                )

    @staticmethod
    def _sanitize_lang(lang: str) -> str:
        """Validate and sanitize a Tesseract language identifier to prevent argument injection.

        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:

View on GitHub (pinned to 61d76f1ff3)

Solutions

Use clean BCP-47/Tesseract language tokens: 'eng', 'deu', 'eng+deu', 'script/Latin'.
Sanitize config-sourced language strings before passing them (strip whitespace, split multi-language tokens with '+').
If you dynamically build lang lists, validate each token with the same rule: ^[A-Za-z0-9_/+\-]+$.

Example fix

# before
TesseractOcrOptions(lang=["eng deu"])

# after
TesseractOcrOptions(lang=["eng+deu"])

Defensive patterns

Strategy: validation

Validate before calling

import re
_VALID_LANG_RE = re.compile(r"^[A-Za-z0-9_/+\-]+$")

def sanitize_langs(langs: list[str]) -> list[str]:
    bad = [l for l in langs if not _VALID_LANG_RE.match(l)]
    if bad:
        raise ValueError(f"invalid tesseract language tokens: {bad}")
    return langs

Type guard

import re

def is_valid_tesseract_lang(token: str) -> bool:
    return bool(re.fullmatch(r"[A-Za-z0-9_/+\-]+", token))

Try / catch

try:
    TesseractOcrCliModel(options=TesseractCliOcrOptions(lang=lang_list))
except ValueError as e:
    if "Invalid Tesseract language identifier" in str(e):
        lang_list = [t for t in lang_list if is_valid_tesseract_lang(t)] or ["eng"]
    else:
        raise

Prevention

Never pass raw user input as tesseract lang tokens; validate with a whitelist regex.
Split multi-language specs with '+' rather than spaces or commas.
Log rejected tokens to detect injection attempts early.

When it happens

Trigger: TesseractOcrOptions(lang=[...]) containing tokens with spaces, quotes, shell metacharacters, semicolons, or other invalid characters. Validation also runs for any configured lang token other than 'auto'.

Common situations: Language lists loaded from user input, JSON/YAML config, or LLM-generated configs; tokens like 'eng deu' (space instead of '+'), 'eng;rm -rf' (injection attempt), or trailing punctuation.

Related errors

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