{"record":{"id":"ed8e7b0057bf43ce","repo":"docling-project/docling","slug":"asr-model-is-not-known","errorCode":null,"errorMessage":"{asr_model} is not known","messagePattern":"(.+?) is not known","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/cli/main.py","lineNumber":370,"sourceCode":"        AsrModelType.WHISPER_TINY_EN_S2T: WHISPER_TINY_EN_S2T,\n        AsrModelType.WHISPER_BASE_S2T: WHISPER_BASE_S2T,\n        AsrModelType.WHISPER_BASE_EN_S2T: WHISPER_BASE_EN_S2T,\n        AsrModelType.WHISPER_SMALL_S2T: WHISPER_SMALL_S2T,\n        AsrModelType.WHISPER_SMALL_EN_S2T: WHISPER_SMALL_EN_S2T,\n        AsrModelType.WHISPER_DISTIL_SMALL_EN_S2T: WHISPER_DISTIL_SMALL_EN_S2T,\n        AsrModelType.WHISPER_MEDIUM_S2T: WHISPER_MEDIUM_S2T,\n        AsrModelType.WHISPER_MEDIUM_EN_S2T: WHISPER_MEDIUM_EN_S2T,\n        AsrModelType.WHISPER_DISTIL_MEDIUM_EN_S2T: WHISPER_DISTIL_MEDIUM_EN_S2T,\n        AsrModelType.WHISPER_LARGE_V3_S2T: WHISPER_LARGE_V3_S2T,\n        AsrModelType.WHISPER_DISTIL_LARGE_V3_S2T: WHISPER_DISTIL_LARGE_V3_S2T,\n        AsrModelType.WHISPER_DISTIL_LARGE_V3_5_S2T: WHISPER_DISTIL_LARGE_V3_5_S2T,\n        AsrModelType.WHISPER_LARGE_V3_TURBO_S2T: WHISPER_LARGE_V3_TURBO_S2T,\n    }\n    try:\n        return mapping[asr_model]\n    except KeyError:\n        _log.error(f\"{asr_model} is not known\")\n        raise ValueError(f\"{asr_model} is not known\")\n\n\napp = typer.Typer(\n    name=\"Docling\",\n    cls=_DefaultCommandGroup,\n    help=(\n        \"Convert documents with Docling. At default verbosity a per-file \"\n        \"progress line is logged; pass -q/--quiet for fully silent output \"\n        \"(useful when calling docling from an AI agent or script).\"\n    ),\n    no_args_is_help=True,\n    add_completion=False,\n    pretty_exceptions_enable=False,\n    epilog=(\n        \"Remote conversion: when installed with the `service-client` extra, \"\n        \"use `docling convert-remote` and read `docling convert-remote --help` \"\n        \"for authentication (DOCLING_SERVICE_URL / DOCLING_SERVICE_API_KEY), \"\n        \"supported options, and exit codes before invoking it.\"","sourceCodeStart":352,"sourceCodeEnd":388,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/cli/main.py#L352-L388","documentation":"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).","triggerScenarios":"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.","commonSituations":"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.","solutions":["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).","Upgrade docling to a consistent version so AsrModelType and the CLI mapping are in sync: `uv sync` / `pip install -U docling`.","If calling programmatically, use the enum member (AsrModelType.WHISPER_TURBO) instead of a raw string.","If writing a wrapper script, validate the model name against the enum before invoking the CLI."],"exampleFix":"# before\ndocling convert audio.mp3 --asr-model whisper_large  # stale/unknown name -> ValueError\n\n# after\ndocling convert audio.mp3 --asr-model whisper_large_v3_s2t","handlingStrategy":"validation","validationCode":"from docling.datamodel.asr_model_specs import AsrModelType\n\ndef valid_asr_model(name: str) -> bool:\n    return name in {m.value for m in AsrModelType}","typeGuard":"from typing import Union\nfrom docling.datamodel.asr_model_specs import AsrModelType\n\ndef as_asr_model(v: str) -> Union[AsrModelType, None]:\n    try:\n        return AsrModelType(v)\n    except ValueError:\n        return None","tryCatchPattern":"try:\n    impl = get_impl(model_name)\nexcept ValueError:\n    print(f'valid models: {[m.value for m in AsrModelType]}')\n    sys.exit(2)","preventionTips":["Source model names from AsrModelType, never hardcode strings.","Keep docling packages at one consistent version to avoid enum/mapping skew.","Validate CLI args against the enum before invoking docling."],"tags":["cli","asr","whisper","version-skew"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}