{"record":{"id":"c80fa33b380e8657","repo":"docling-project/docling","slug":"easyocr-languages-requires-with-easyocr-true","errorCode":null,"errorMessage":"easyocr_languages requires with_easyocr=True","messagePattern":"easyocr_languages requires with_easyocr=True","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/utils/model_downloader.py","lineNumber":76,"sourceCode":"    with_code_formula: bool = True,\n    with_picture_classifier: bool = True,\n    with_smolvlm: bool = False,\n    with_granitedocling: bool = False,\n    with_granitedocling_mlx: bool = False,\n    with_granitedocling_2stage: bool = False,\n    with_smoldocling: bool = False,\n    with_smoldocling_mlx: bool = False,\n    with_granite_vision: bool = False,\n    with_granite_chart_extraction: bool = False,\n    with_granite_chart_extraction_v4: bool = False,\n    with_rapidocr: bool = True,\n    rapidocr_models: Optional[list[str]] = None,\n    with_easyocr: bool = False,\n    easyocr_languages: Optional[list[str]] = None,\n    with_nemotron_ocr: bool = False,\n):\n    if easyocr_languages is not None and not with_easyocr:\n        raise ValueError(\"easyocr_languages requires with_easyocr=True\")\n    if rapidocr_models is not None and not with_rapidocr:\n        raise ValueError(\"rapidocr_models requires with_rapidocr=True\")\n\n    easyocr_recognition_models = [\"english_g2\", \"latin_g2\"]\n    if easyocr_languages is not None:\n        easyocr_recognition_models = _resolve_easyocr_recognition_models(\n            easyocr_languages\n        )\n\n    if output_dir is None:\n        output_dir = settings.cache_dir / \"models\"\n\n    # Make sure the folder exists\n    output_dir.mkdir(exist_ok=True, parents=True)\n\n    if with_layout:\n        _log.info(\"Downloading layout model...\")\n        layout_spec = LayoutObjectDetectionOptions().model_spec","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/utils/model_downloader.py#L58-L94","documentation":"ValueError raised at the top of download_models() when easyocr_languages is provided (not None) while with_easyocr is False. It is a fail-fast argument-consistency guard: language lists are meaningless unless EasyOCR model downloading is enabled, so the function refuses to silently ignore the option.","triggerScenarios":"Calling download_models(easyocr_languages=['fr','de'], with_easyocr=False) — explicitly or via a wrapper/CLI that forwards language settings without toggling the EasyOCR flag.","commonSituations":"Reusing a download script that adds languages after previously disabling EasyOCR; enabling EasyOCR only in the pipeline options but not in the download call; CLI flags combined incorrectly (--easyocr-languages without --easyocr).","solutions":["Set with_easyocr=True alongside easyocr_languages","Or remove easyocr_languages if EasyOCR is intentionally disabled","Audit shared download helpers so the two options are set together"],"exampleFix":"# before\ndownload_models(with_easyocr=False, easyocr_languages=[\"fr\", \"de\"])\n\n# after\ndownload_models(with_easyocr=True, easyocr_languages=[\"fr\", \"de\"])","handlingStrategy":"validation","validationCode":"if easyocr_languages and not with_easyocr:\n    with_easyocr = True  # or raise early with your own message\ndownload_models(with_easyocr=with_easyocr, easyocr_languages=easyocr_languages)","typeGuard":"def easyocr_args_consistent(with_easyocr: bool, easyocr_languages) -> bool:\n    return easyocr_languages is None or with_easyocr","tryCatchPattern":"try:\n    download_models(with_easyocr=flags.easyocr, easyocr_languages=flags.easyocr_langs)\nexcept ValueError as exc:\n    if \"with_easyocr\" in str(exc):\n        flags.easyocr = True\n        download_models(with_easyocr=True, easyocr_languages=flags.easyocr_langs)\n    else:\n        raise","preventionTips":["Treat with_easyocr and easyocr_languages as one unit in CLI parsing — set both together","Write a small wrapper that asserts option consistency before calling download_models","Default easyocr_languages to None when the OCR backend is disabled","Add a startup assertion in shared download scripts"],"tags":["model-download","easyocr","input-validation","ocr"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}