docling-project/docling · error · ValueError

{asr_model} is not known

Error message

{asr_model} is not known

What it means

Raised by the docling CLI's ASR model resolution function when the given AsrModelType value has no entry in the mapping dict of model type to implementation. Since the mapping is keyed by enum members, this only fires when a value bypasses the enum (e.g., raw string not in the enum, or an enum member added to AsrModelType but missing from the mapping after a partial upgrade).

Source

Thrown at docling/cli/main.py:370

        AsrModelType.WHISPER_TINY_EN_S2T: WHISPER_TINY_EN_S2T,
        AsrModelType.WHISPER_BASE_S2T: WHISPER_BASE_S2T,
        AsrModelType.WHISPER_BASE_EN_S2T: WHISPER_BASE_EN_S2T,
        AsrModelType.WHISPER_SMALL_S2T: WHISPER_SMALL_S2T,
        AsrModelType.WHISPER_SMALL_EN_S2T: WHISPER_SMALL_EN_S2T,
        AsrModelType.WHISPER_DISTIL_SMALL_EN_S2T: WHISPER_DISTIL_SMALL_EN_S2T,
        AsrModelType.WHISPER_MEDIUM_S2T: WHISPER_MEDIUM_S2T,
        AsrModelType.WHISPER_MEDIUM_EN_S2T: WHISPER_MEDIUM_EN_S2T,
        AsrModelType.WHISPER_DISTIL_MEDIUM_EN_S2T: WHISPER_DISTIL_MEDIUM_EN_S2T,
        AsrModelType.WHISPER_LARGE_V3_S2T: WHISPER_LARGE_V3_S2T,
        AsrModelType.WHISPER_DISTIL_LARGE_V3_S2T: WHISPER_DISTIL_LARGE_V3_S2T,
        AsrModelType.WHISPER_DISTIL_LARGE_V3_5_S2T: WHISPER_DISTIL_LARGE_V3_5_S2T,
        AsrModelType.WHISPER_LARGE_V3_TURBO_S2T: WHISPER_LARGE_V3_TURBO_S2T,
    }
    try:
        return mapping[asr_model]
    except KeyError:
        _log.error(f"{asr_model} is not known")
        raise ValueError(f"{asr_model} is not known")


app = typer.Typer(
    name="Docling",
    cls=_DefaultCommandGroup,
    help=(
        "Convert documents with Docling. At default verbosity a per-file "
        "progress line is logged; pass -q/--quiet for fully silent output "
        "(useful when calling docling from an AI agent or script)."
    ),
    no_args_is_help=True,
    add_completion=False,
    pretty_exceptions_enable=False,
    epilog=(
        "Remote conversion: when installed with the `service-client` extra, "
        "use `docling convert-remote` and read `docling convert-remote --help` "
        "for authentication (DOCLING_SERVICE_URL / DOCLING_SERVICE_API_KEY), "
        "supported options, and exit codes before invoking it."

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Check docling.datamodel.asr_model_specs.AsrModelType for the exact valid values and use one of them (e.g., whisper_large_v3_s2t, whisper_turbo).
2. Upgrade docling to a consistent version so AsrModelType and the CLI mapping are in sync: `uv sync` / `pip install -U docling`.
3. If calling programmatically, use the enum member (AsrModelType.WHISPER_TURBO) instead of a raw string.
4. If writing a wrapper script, validate the model name against the enum before invoking the CLI.

Example fix

# before
docling convert audio.mp3 --asr-model whisper_large  # stale/unknown name -> ValueError

# after
docling convert audio.mp3 --asr-model whisper_large_v3_s2t

from docling.datamodel.asr_model_specs import AsrModelType

def valid_asr_model(name: str) -> bool:
    return name in {m.value for m in AsrModelType}

from typing import Union
from docling.datamodel.asr_model_specs import AsrModelType

def as_asr_model(v: str) -> Union[AsrModelType, None]:
    try:
        return AsrModelType(v)
    except ValueError:
        return None

try:
    impl = get_impl(model_name)
except ValueError:
    print(f'valid models: {[m.value for m in AsrModelType]}')
    sys.exit(2)

When it happens

Trigger: Passing an unrecognized --asr-model string to the docling CLI; version skew where AsrModelType (defined in docling/datamodel/asr_model_specs.py) gained new members (e.g., new _S2T variants) but the installed cli/main.py mapping predates them; constructing the enum from bad input elsewhere.

Common situations: Upgrading docling-core or the specs module without upgrading the CLI package; typos in model names in scripts wrapping the CLI; mixing docling package versions in one environment.

Related errors

• Model `{self.repo_id}` is English-only and does not support
• Model `{self.repo_id}` does not support the `translate` task
• whisper is not installed. Please install it via `pip install
• whisper is not installed. Unfortunately its dependencies are
• artifacts_path ({artifacts_path}) does not contain the check

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