{"record":{"id":"61109748523be429","repo":"opendatalab/MinerU","slug":"language-lang-not-supported-allowed-values-pu","errorCode":null,"errorMessage":"Language {lang} not supported. Allowed values: {PUBLIC_OCR_LANGUAGES joined by ', '}","messagePattern":"Language (.+?) not supported\\. Allowed values: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"mineru/utils/ocr_language.py","lineNumber":121,"sourceCode":"def format_public_ocr_lang_description() -> str:\n    \"\"\"生成公开 API 使用的 OCR 语言说明，避免入口文案各自维护。\"\"\"\n    option_lines = [\n        f\"- {lang}: {_PUBLIC_OCR_LANGUAGE_DESCRIPTIONS[lang]}.\"\n        for lang in PUBLIC_OCR_LANGUAGES\n    ]\n    return (\n        \"(Adapted for pipeline backend only) Input the languages in the pdf \"\n        \"to improve OCR accuracy. Options:\\n\"\n        + \"\\n\".join(option_lines)\n    )\n\n\ndef validate_public_ocr_lang(lang: str) -> str:\n    \"\"\"校验公开入口允许的 OCR 语言，并将兼容入口规范到实际模型 key。\"\"\"\n    if lang in _CH_LANG_ALIASES:\n        return \"ch\"\n    if lang not in PUBLIC_OCR_LANGUAGES:\n        raise ValueError(\n            f\"Language {lang} not supported. Allowed values: \"\n            + \", \".join(PUBLIC_OCR_LANGUAGES)\n        )\n    return lang\n\n\ndef validate_public_ocr_lang_list(lang_list: list[str]) -> list[str]:\n    \"\"\"校验公开 API 的语言列表，返回可安全传入下游的副本。\"\"\"\n    effective_lang_list = lang_list or [\"ch\"]\n    return [validate_public_ocr_lang(lang) for lang in effective_lang_list]\n\n\ndef normalize_ocr_model_lang(\n    lang: str | None,\n    *,\n    device: str | None = None,\n    supported_langs=None,\n) -> str:","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/opendatalab/MinerU/blob/4fe4bde114a23ee5dd637eae99b767f4669bf58c/mineru/utils/ocr_language.py#L103-L139","documentation":"Raised by validate_public_ocr_lang() when an OCR language code passed through MineRU's public API is not in PUBLIC_OCR_LANGUAGES and not one of the Chinese aliases. The public API intentionally exposes a smaller allow-list than the full PaddleOCR language set; inputs are normalized (aliases like 'ch_server'/'chinese' map to 'ch') before the check, so this error means the code is genuinely outside the supported set. The message lists every allowed value.","triggerScenarios":"Calling a public API entry (via validate_public_ocr_lang_list) with e.g. lang='korean', 'jp', 'french', or a typo like 'ch1'/'china' — anything not in PUBLIC_OCR_LANGUAGES and not a registered _CH_LANG_ALIASES entry.","commonSituations":"Porting code from the internal API that accepts raw PaddleOCR lang codes (like 'korean' or 'japan') to the public API which does not; guessing language codes ('en-US', 'CH', 'zh') instead of using the documented values; passing the display name ('Chinese') rather than the code.","solutions":["Use one of the values listed in the error message (e.g. 'ch', 'en', and the other PUBLIC_OCR_LANGUAGES entries) — copy the exact code from the message, it enumerates everything allowed.","For Chinese variants use the alias set ('chinese', 'ch_sim', 'ch_server', etc.) which normalize to 'ch'; do not invent new spellings.","If you need a language the public API rejects, check the internal normalization path (normalize_lang, error 151) or open a feature request — do not bypass validation, downstream model loading will fail on unknown keys."],"exampleFix":"# before\nresult = client.parse(pdf, lang_list=['korean'])\n\n# after\nresult = client.parse(pdf, lang_list=['ch', 'en'])  # only PUBLIC_OCR_LANGUAGES values","handlingStrategy":"validation","validationCode":"from mineru.utils.ocr_language import PUBLIC_OCR_LANGUAGES, validate_public_ocr_lang_list\n\nlangs = ['ch', 'en']\nassert all(l in PUBLIC_OCR_LANGUAGES or l.lower() in ('chinese', 'ch_sim', 'ch_server') for l in langs)\n# or simply let validate_public_ocr_lang_list() run before submitting the job:\nlangs = validate_public_ocr_lang_list(langs)","typeGuard":"from typing import TypeGuard\n\ndef is_supported_public_lang(lang: object) -> TypeGuard[str]:\n    return isinstance(lang, str) and (lang in PUBLIC_OCR_LANGUAGES or lang in _CH_LANG_ALIASES)","tryCatchPattern":"try:\n    langs = validate_public_ocr_lang_list(request.lang_list)\nexcept ValueError as e:\n    return HTTPException(status_code=422, detail=str(e))  # echoes the full allowed list","preventionTips":["Validate lang_list with validate_public_ocr_lang_list() at the request boundary and return the message verbatim — it lists every legal value.","Expose PUBLIC_OCR_LANGUAGES as the choices in your CLI/OpenAPI schema so invalid values are rejected before MineRU is invoked.","Do not reuse raw PaddleOCR language codes in the public API surface; map them explicitly."],"tags":["ocr","validation","language","mineru"],"backgroundTag":null,"analyzedSha":"4fe4bde114a23ee5dd637eae99b767f4669bf58c","analyzedAt":"2026-08-14T21:29:18.456Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}