opendatalab/MinerU · error · ValueError

Language {lang} not supported. Allowed values: {PUBLIC_OCR_L

Error message

Language {lang} not supported. Allowed values: {PUBLIC_OCR_LANGUAGES joined by ', '}

What it means

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.

Source

Thrown at mineru/utils/ocr_language.py:121

def format_public_ocr_lang_description() -> str:
    """生成公开 API 使用的 OCR 语言说明，避免入口文案各自维护。"""
    option_lines = [
        f"- {lang}: {_PUBLIC_OCR_LANGUAGE_DESCRIPTIONS[lang]}."
        for lang in PUBLIC_OCR_LANGUAGES
    ]
    return (
        "(Adapted for pipeline backend only) Input the languages in the pdf "
        "to improve OCR accuracy. Options:\n"
        + "\n".join(option_lines)
    )


def validate_public_ocr_lang(lang: str) -> str:
    """校验公开入口允许的 OCR 语言，并将兼容入口规范到实际模型 key。"""
    if lang in _CH_LANG_ALIASES:
        return "ch"
    if lang not in PUBLIC_OCR_LANGUAGES:
        raise ValueError(
            f"Language {lang} not supported. Allowed values: "
            + ", ".join(PUBLIC_OCR_LANGUAGES)
        )
    return lang


def validate_public_ocr_lang_list(lang_list: list[str]) -> list[str]:
    """校验公开 API 的语言列表，返回可安全传入下游的副本。"""
    effective_lang_list = lang_list or ["ch"]
    return [validate_public_ocr_lang(lang) for lang in effective_lang_list]


def normalize_ocr_model_lang(
    lang: str | None,
    *,
    device: str | None = None,
    supported_langs=None,
) -> str:

View on GitHub (pinned to 4fe4bde114)

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.

Example fix

# before
result = client.parse(pdf, lang_list=['korean'])

# after
result = client.parse(pdf, lang_list=['ch', 'en'])  # only PUBLIC_OCR_LANGUAGES values

Defensive patterns

Strategy: validation

Validate before calling

from mineru.utils.ocr_language import PUBLIC_OCR_LANGUAGES, validate_public_ocr_lang_list

langs = ['ch', 'en']
assert all(l in PUBLIC_OCR_LANGUAGES or l.lower() in ('chinese', 'ch_sim', 'ch_server') for l in langs)
# or simply let validate_public_ocr_lang_list() run before submitting the job:
langs = validate_public_ocr_lang_list(langs)

Type guard

from typing import TypeGuard

def is_supported_public_lang(lang: object) -> TypeGuard[str]:
    return isinstance(lang, str) and (lang in PUBLIC_OCR_LANGUAGES or lang in _CH_LANG_ALIASES)

Try / catch

try:
    langs = validate_public_ocr_lang_list(request.lang_list)
except ValueError as e:
    return HTTPException(status_code=422, detail=str(e))  # echoes the full allowed list

Prevention

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.

When it happens

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

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

Related errors

AI-assisted analysis of opendatalab/MinerU@4fe4bde114 (2026-08-14). Data as JSON: /api/errors/61109748523be429. Report an issue: GitHub.