{"record":{"id":"8fe08dbd03603a92","repo":"docling-project/docling","slug":"rapidocr-models-requires-with-rapidocr-true","errorCode":null,"errorMessage":"rapidocr_models requires with_rapidocr=True","messagePattern":"rapidocr_models requires with_rapidocr=True","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/utils/model_downloader.py","lineNumber":78,"sourceCode":"    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\n        # Fetch every engine variant: e.g. the ONNX engine reads from its own repo.\n        layout_repos = {layout_spec.repo_id: layout_spec.revision}","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/utils/model_downloader.py#L60-L96","documentation":"ValueError raised at the top of download_models() when rapidocr_models is provided (not None) while with_rapidocr is False. Note with_rapidocr defaults to True, so this only fires when the caller explicitly disabled RapidOCR yet still passed a model spec list — a fail-fast guard against silently ignored options.","triggerScenarios":"Calling download_models(rapidocr_models=['torch:en'], with_rapidocr=False); typically a wrapper that forwards a models list while switching the OCR backend off (e.g. moving to EasyOCR).","commonSituations":"Migrating download scripts from RapidOCR to EasyOCR/Nemotron and turning with_rapidocr off but leaving rapidocr_models in the call; templated/flag-generated calls where the two settings come from different sources.","solutions":["Set with_rapidocr=True (or simply omit it — default is True) when passing rapidocr_models","Or drop rapidocr_models when RapidOCR is intentionally disabled","Keep OCR backend choice and its model list in one config object so they cannot diverge"],"exampleFix":"# before\ndownload_models(with_rapidocr=False, rapidocr_models=[\"torch:en\"])\n\n# after\ndownload_models(with_rapidocr=True, rapidocr_models=[\"torch:en\"])","handlingStrategy":"validation","validationCode":"if rapidocr_models and not with_rapidocr:\n    with_rapidocr = True  # or drop the models list\ndownload_models(with_rapidocr=with_rapidocr, rapidocr_models=rapidocr_models)","typeGuard":"def rapidocr_args_consistent(with_rapidocr: bool, rapidocr_models) -> bool:\n    return rapidocr_models is None or with_rapidocr","tryCatchPattern":"try:\n    download_models(with_rapidocr=flags.rapidocr, rapidocr_models=flags.rapidocr_models)\nexcept ValueError as exc:\n    if \"with_rapidocr\" in str(exc):\n        download_models(with_rapidocr=True, rapidocr_models=flags.rapidocr_models)\n    else:\n        raise","preventionTips":["Remember with_rapidocr defaults to True — only explicit False plus a models list triggers this","Bind the OCR backend choice and its model list in a single dataclass/config","Validate option pairs in your download wrapper before calling download_models","When switching OCR backends, delete the old backend's model list, don't just flip the flag"],"tags":["model-download","rapidocr","input-validation","ocr"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}