{"record":{"id":"3f6c83785aaa6713","repo":"docling-project/docling","slug":"tesseract-is-not-available-aborting-exc-instal","errorCode":null,"errorMessage":"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.","messagePattern":"Tesseract is not available, aborting: (.+?) 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\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/models/stages/ocr/tesseract_ocr_cli_model.py","lineNumber":83,"sourceCode":"        # so that all subsequent subprocess calls use only these already-validated values.\n        self._safe_tesseract_cmd: str = self._sanitize_cmd(self.options.tesseract_cmd)\n        self._safe_tessdata_path: Optional[str] = (\n            self._sanitize_path(self.options.path)\n            if self.options.path is not None\n            else None\n        )\n        if self.options.lang:\n            for _lang_token in self.options.lang:\n                if _lang_token != \"auto\":\n                    self._sanitize_lang(_lang_token)\n\n        if self.enabled:\n            try:\n                self._get_name_and_version()\n                self._set_languages_and_prefix()\n\n            except Exception as exc:\n                raise RuntimeError(\n                    f\"Tesseract is not available, aborting: {exc} \"\n                    \"Install tesseract on your system and the tesseract binary is discoverable. \"\n                    \"The actual command for Tesseract can be specified in `pipeline_options.ocr_options.tesseract_cmd='tesseract'`. \"\n                    \"Alternatively, Docling has support for other OCR engines. See the documentation.\"\n                )\n\n    @staticmethod\n    def _sanitize_lang(lang: str) -> str:\n        \"\"\"Validate and sanitize a Tesseract language identifier to prevent argument injection.\n\n        Valid identifiers (e.g. ``eng``, ``script/Latin``, ``eng+deu``) contain only\n        alphanumeric characters, underscores, hyphens, forward slashes, and plus signs.\n        \"\"\"\n        if not _VALID_LANG_RE.match(lang):\n            raise ValueError(\n                f\"Invalid Tesseract language identifier: {lang!r}. \"\n                \"Language identifiers must only contain alphanumeric characters, \"\n                \"underscores, hyphens, forward slashes, and plus signs.\"","sourceCodeStart":65,"sourceCodeEnd":101,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/stages/ocr/tesseract_ocr_cli_model.py#L65-L101","documentation":"The CLI-based Tesseract OCR model runs 'tesseract --version' and reads available languages at init. Any exception there (binary not found, not executable, version output unparsable, requested language packs missing) is wrapped in this RuntimeError with remediation hints, including the tesseract_cmd override.","triggerScenarios":"pipeline_options.ocr_options = TesseractOcrOptions() with the tesseract binary absent from PATH; tesseract_cmd pointing to a wrong location; or the system tesseract install broken so that --version or language listing fails.","commonSituations":"Slim Docker images / CI runners without the tesseract package; macOS/Windows where tesseract is installed but not on PATH; custom tesseract builds installed at non-standard locations.","solutions":["Install Tesseract on the system (apt-get install tesseract-ocr, brew install tesseract, or choco install tesseract) and ensure 'tesseract --version' works in the same shell.","If installed at a custom location, point Docling at it: pipeline_options.ocr_options.tesseract_cmd = '/usr/local/bin/tesseract'.","Alternatively pick a different OCR engine (e.g. RapidOCR) or install the docling extras that bundle an engine."],"exampleFix":"# before\n# RuntimeError: Tesseract is not available (binary not on PATH)\n\n# after\n$ apt-get install -y tesseract-ocr\n# or in code:\npipeline_options.ocr_options.tesseract_cmd = \"/usr/local/bin/tesseract\"","handlingStrategy":"validation","validationCode":"import shutil, subprocess\n\ncmd = tesseract_cmd or \"tesseract\"\nif shutil.which(cmd) is None:\n    raise SystemExit(f\"tesseract binary {cmd!r} not found on PATH\")\nsubprocess.run([cmd, \"--version\"], capture_output=True, check=True)","typeGuard":null,"tryCatchPattern":"try:\n    TesseractOcrCliModel(options=TesseractCliOcrOptions())\nexcept RuntimeError as e:\n    if \"Tesseract is not available\" in str(e):\n        log.error(\"install tesseract or set tesseract_cmd: %s\", e)\n        raise\n    raise","preventionTips":["Install tesseract in your base Docker image and smoke-test 'tesseract --version' in CI.","Set tesseract_cmd explicitly in containers to avoid PATH surprises.","Add the needed language packs (e.g. tesseract-ocr-eng) alongside the binary."],"tags":["ocr","tesseract","environment","dependency"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}