docling-project/docling · error · ValueError

Model `{self.repo_id}` is English-only and does not support

Error message

Model `{self.repo_id}` is English-only and does not support language `{self.language}`. Set language='en' or choose a multilingual model (e.g., `tiny`, `base`, `small`, `medium`, `large-v3`).

What it means

Model validator on InlineAsrWhisperS2TOptions: the configured repo_id is in _ENGLISH_ONLY_S2T_REPOS (English-only WhisperS2T checkpoints like the *.en and distil-en models) but language is set to anything other than 'en'. English-only checkpoints have no multilingual decoder, so decoding any other language is impossible and rejected at options construction time.

Source

Thrown at docling/datamodel/pipeline_options_asr_model.py:433

            description=(
                "Optional text prompt to condition the transcription style or "
                "provide context. Useful for domain-specific vocabulary."
            )
        ),
    ] = None
    supported_devices: Annotated[
        list[AcceleratorDevice],
        Field(description=("Hardware accelerators supported by WhisperS2T.")),
    ] = [
        AcceleratorDevice.CPU,
        AcceleratorDevice.CUDA,
    ]

    @model_validator(mode="after")
    def _validate_repo_capabilities(self) -> "InlineAsrWhisperS2TOptions":
        # Reject non-English language for English-only repos
        if self.repo_id in _ENGLISH_ONLY_S2T_REPOS and self.language != "en":
            raise ValueError(
                f"Model `{self.repo_id}` is English-only and does not support "
                f"language `{self.language}`. Set language='en' or choose a "
                f"multilingual model (e.g., `tiny`, `base`, `small`, `medium`, "
                f"`large-v3`)."
            )
        # Reject translate task for repos without translate capability
        if self.repo_id in _NO_TRANSLATE_S2T_REPOS and self.task == "translate":
            raise ValueError(
                f"Model `{self.repo_id}` does not support the `translate` task. "
                f"Set task='transcribe' or choose a multilingual model with "
                f"translation capability (e.g., `large-v3`)."
            )
        return self

View on GitHub (pinned to 61d76f1ff3)

Solutions

Set language='en' when using an English-only repo.
Or switch to a multilingual checkpoint (tiny, base, small, medium, large-v3) as the message suggests.
Centralize the language/model pairing in config so changing a model resets language to 'en'.

Example fix

# before
InlineAsrWhisperS2TOptions(repo_id='distil-whisper/distil-large-v3.en', language='de')  # ValueError

# after
InlineAsrWhisperS2TOptions(repo_id='distil-whisper/distil-large-v3.en', language='en')

Defensive patterns

Strategy: validation

Validate before calling

ENGLISH_ONLY = _ENGLISH_ONLY_S2T_REPOS  # from docling.datamodel.pipeline_options_asr_model

def language_ok_for_repo(repo_id: str, language: str) -> bool:
    return repo_id not in ENGLISH_ONLY or language == 'en'

Prevention

Pin language='en' whenever selecting an English-only or distil-en checkpoint.
Centralize repo_id/language pairs in config so they cannot drift apart.
Prefer multilingual checkpoints when language is user-configurable.

When it happens

Trigger: Building InlineAsrWhisperS2TOptions with an English-only repo (e.g., a distil-large-v3-en style checkpoint) together with language='fr' or any non-'en' value; defaults or config files that set a global language for all ASR models and are then reused with an English-only model.

Common situations: Shared ASR config across a multilingual pipeline switched to a faster English-distilled model without resetting language; auto-detection language settings ('auto' or None-style values) that count as non-'en'.

Related errors

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