opendatalab/MinerU · error · ValueError

model source auto is only supported for internal default det

Error message

model source auto is only supported for internal default detection or explicit download command selection.

What it means

Raised by resolve_model_source() when the model source resolves to the literal 'auto' but auto-detection is not permitted at that call site (allow_auto is False). 'auto' is only legal when it comes from MineRU's own internal default (no configured source) or from an explicit download-command selection; an explicit 'auto' string coming from the config file reaches this branch without allow_auto and is rejected. This mirrors error 144 but for config-file-supplied values rather than the env var.

Source

Thrown at mineru/utils/models_download_utils.py:237

                "or set it to huggingface/modelscope/local."
            )
    if model_source is None:
        model_source = get_configured_model_source()
    if model_source is None:
        model_source = "auto"
        allow_auto = True

    if not isinstance(model_source, str):
        logger.warning(f"Unsupported model source type: {type(model_source)}, fallback to auto.")
        model_source = "auto"
        allow_auto = True

    normalized_model_source = model_source.strip().lower()
    if normalized_model_source == "local":
        return "local"
    if normalized_model_source == "auto":
        if not allow_auto:
            raise ValueError(
                "model source auto is only supported for internal default detection "
                "or explicit download command selection."
            )
        resolved_model_source = resolve_auto_model_source()
        persist_resolved_model_source(resolved_model_source)
        return resolved_model_source
    if normalized_model_source in REMOTE_MODEL_SOURCES:
        return normalized_model_source

    logger.warning(f"Unsupported model source: {model_source}, fallback to auto.")
    resolved_model_source = resolve_auto_model_source()
    persist_resolved_model_source(resolved_model_source)
    return resolved_model_source


@lru_cache(maxsize=None)
def _snapshot_download_cached(model_source: str, repo_mode: str, repo: str, relative_path: str) -> str:
    """按进程缓存远端 snapshot_download 结果，减少重复缓存检查和 Fetching 日志。"""

View on GitHub (pinned to 4fe4bde114)

Solutions

Remove the model-source key from the config file so MineRU falls back to internal detection (which sets allow_auto=True) and persists the resolved source.
Or set a concrete value in the config: "model-source": "huggingface" | "modelscope" | "local".
Ensure MINERU_MODEL_SOURCE is not set to auto either (see the companion env-var error).
After fixing, let the first download run once — detection picks a reachable mirror and persists it, so subsequent runs skip detection.

Example fix

// before (mineru.json)
{ "model-source": "auto" }

// after
{ "model-source": "modelscope" }
// or simply omit the key

Defensive patterns

Strategy: validation

Validate before calling

import json, os
cfg = json.load(open(os.path.expanduser('~/mineru.json')))
src = cfg.get('model-source')
assert src is None or str(src).strip().lower() in {'huggingface', 'modelscope', 'local'}, \
    f'model-source={src!r} invalid; remove the key or use a concrete source'

Type guard

def valid_config_model_source(cfg: dict) -> bool:
    src = cfg.get('model-source')
    return src is None or (isinstance(src, str) and src.strip().lower() in {'huggingface', 'modelscope', 'local'})

Try / catch

try:
    resolve_model_source()
except ValueError as e:
    if 'auto is only supported' in str(e):
        raise SystemExit('Remove "model-source": "auto" from mineru.json; omit the key or set a concrete source')
    raise

Prevention

Validate the config file's model-source key at deploy time against the explicit allow-list.
Omit model-source entirely when you want detection; absence is the supported way to say auto.
After a first successful auto-detected download, read the persisted source and pin it in config for reproducible deployments.

When it happens

Trigger: Setting "model-source": "auto" (or a value that normalizes to auto) in the config file so get_configured_model_source() returns it, then calling resolve_model_source() with allow_auto=False — the default for library callers.

Common situations: The mineru.json config was hand-edited or migrated with model-source: auto left in; documentation examples show auto as a config value; a downgrade/upgrade between versions changed whether config-file auto is accepted.

Related errors

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