docling-project/docling · error · ValueError

easyocr_languages requires with_easyocr=True

Error message

easyocr_languages requires with_easyocr=True

What it means

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.

Source

Thrown at docling/utils/model_downloader.py:76

    with_code_formula: bool = True,
    with_picture_classifier: bool = True,
    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

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Set with_easyocr=True alongside easyocr_languages
2. Or remove easyocr_languages if EasyOCR is intentionally disabled
3. Audit shared download helpers so the two options are set together

Example fix

# before
download_models(with_easyocr=False, easyocr_languages=["fr", "de"])

# after
download_models(with_easyocr=True, easyocr_languages=["fr", "de"])

if easyocr_languages and not with_easyocr:
    with_easyocr = True  # or raise early with your own message
download_models(with_easyocr=with_easyocr, easyocr_languages=easyocr_languages)

def easyocr_args_consistent(with_easyocr: bool, easyocr_languages) -> bool:
    return easyocr_languages is None or with_easyocr

try:
    download_models(with_easyocr=flags.easyocr, easyocr_languages=flags.easyocr_langs)
except ValueError as exc:
    if "with_easyocr" in str(exc):
        flags.easyocr = True
        download_models(with_easyocr=True, easyocr_languages=flags.easyocr_langs)
    else:
        raise

When it happens

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

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

Related errors

• rapidocr_models requires with_rapidocr=True
• Unsupported EasyOCR language code: {language}
• EasyOCR is not installed. Please install it via `pip install
• ZIP slip attempt: {member.filename}
• Nemotron OCR artifacts not found or incomplete in artifacts_

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