docling-project/docling · error · ValueError

rapidocr_models requires with_rapidocr=True

Error message

rapidocr_models requires with_rapidocr=True

What it means

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.

Source

Thrown at docling/utils/model_downloader.py:78

    with_smolvlm: bool = False,
    with_granitedocling: bool = False,
    with_granitedocling_mlx: bool = False,
    with_granitedocling_2stage: bool = False,
    with_smoldocling: bool = False,
    with_smoldocling_mlx: bool = False,
    with_granite_vision: bool = False,
    with_granite_chart_extraction: bool = False,
    with_granite_chart_extraction_v4: bool = False,
    with_rapidocr: bool = True,
    rapidocr_models: Optional[list[str]] = None,
    with_easyocr: bool = False,
    easyocr_languages: Optional[list[str]] = None,
    with_nemotron_ocr: bool = False,
):
    if easyocr_languages is not None and not with_easyocr:
        raise ValueError("easyocr_languages requires with_easyocr=True")
    if rapidocr_models is not None and not with_rapidocr:
        raise ValueError("rapidocr_models requires with_rapidocr=True")

    easyocr_recognition_models = ["english_g2", "latin_g2"]
    if easyocr_languages is not None:
        easyocr_recognition_models = _resolve_easyocr_recognition_models(
            easyocr_languages
        )

    if output_dir is None:
        output_dir = settings.cache_dir / "models"

    # Make sure the folder exists
    output_dir.mkdir(exist_ok=True, parents=True)

    if with_layout:
        _log.info("Downloading layout model...")
        layout_spec = LayoutObjectDetectionOptions().model_spec
        # Fetch every engine variant: e.g. the ONNX engine reads from its own repo.
        layout_repos = {layout_spec.repo_id: layout_spec.revision}

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Set with_rapidocr=True (or simply omit it — default is True) when passing rapidocr_models
2. Or drop rapidocr_models when RapidOCR is intentionally disabled
3. Keep OCR backend choice and its model list in one config object so they cannot diverge

Example fix

# before
download_models(with_rapidocr=False, rapidocr_models=["torch:en"])

# after
download_models(with_rapidocr=True, rapidocr_models=["torch:en"])

if rapidocr_models and not with_rapidocr:
    with_rapidocr = True  # or drop the models list
download_models(with_rapidocr=with_rapidocr, rapidocr_models=rapidocr_models)

def rapidocr_args_consistent(with_rapidocr: bool, rapidocr_models) -> bool:
    return rapidocr_models is None or with_rapidocr

try:
    download_models(with_rapidocr=flags.rapidocr, rapidocr_models=flags.rapidocr_models)
except ValueError as exc:
    if "with_rapidocr" in str(exc):
        download_models(with_rapidocr=True, rapidocr_models=flags.rapidocr_models)
    else:
        raise

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• easyocr_languages requires with_easyocr=True
• Nemotron OCR artifacts not found or incomplete in artifacts_
• Invalid RapidOCR model spec {value!r}. Expected '<backend>:<
• Unknown RapidOCR backend {backend!r} in {value!r}. Supported
• Invalid RapidOCR model spec {value!r}: {err}

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