HKUDS/DeepTutor · error · MinerUError

MinerU cloud mode is selected but no API token is configured

Error message

MinerU cloud mode is selected but no API token is configured. Add a token in Settings → MinerU, or switch to local mode.

What it means

Cloud mode was selected but config.api_keys is empty, so parse_cloud refuses before any network call.

Source

Thrown at deeptutor/services/parsing/engines/mineru/cloud.py:71

def parse_cloud(
    pdf_path: Path,
    output_base: Path,
    config: MinerUConfig,
    *,
    poll_interval: float = DEFAULT_POLL_INTERVAL_SECONDS,
    timeout: float = DEFAULT_TIMEOUT_SECONDS,
    on_progress: Callable[[str], None] | None = None,
) -> Path:
    """Parse ``pdf_path`` via the MinerU cloud API; return the working dir.

    The working dir sits under ``output_base`` (named after the PDF stem) and
    holds the unzipped MinerU artifacts. ``on_progress`` (if given) receives a
    short status line whenever the polled task state / page count changes.
    Raises :class:`MinerUError` on any misconfiguration, API error, timeout,
    or extraction failure.
    """
    if not config.api_keys:
        raise MinerUError(
            "MinerU cloud mode is selected but no API token is configured. "
            "Add a token in Settings → MinerU, or switch to local mode."
        )
    pdf_path = Path(pdf_path)
    if not pdf_path.is_file():
        raise MinerUError(f"PDF file not found: {pdf_path}")

    base_url = config.api_base_url.rstrip("/")
    key_pool = KeyPool(config.api_keys)

    def report(message: str) -> None:
        if on_progress is None:
            return
        try:
            on_progress(message)
        except Exception:
            logger.debug("on_progress callback failed", exc_info=True)

View on GitHub (pinned to 3e82f13042)

Solutions

1. Add a MinerU API token in Settings → MinerU.
2. Or switch mode to local (requires mineru installed).
3. In code, assert config.api_keys before calling.

Example fix

# before
result = parse_pdf_to_workdir(pdf, workdir, config)  # mode=cloud, no keys

# after
if not config.api_keys:
    raise ValueError("configure MinerU API token first")
result = parse_pdf_to_workdir(pdf, workdir, config)

if mode == "cloud" and not cfg.api_keys:
    raise ValueError("MinerU cloud token missing — configure it before parsing")

try:
    parse_cloud(...)
except MinerUError as e:
    if "no API token" in str(e):
        prompt_user_for_token()

When it happens

Trigger: Calling parse_pdf_to_workdir (or parse_cloud) with mode=cloud and no API token saved in Settings → MinerU.

Common situations: Fresh install without configuring a token, settings JSON reset, or a test env lacking credentials.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

• No API token configured.
• _http_error_message(exc)
• Anthropic API key is missing from the active LLM profile.
• Cohere API key is missing from the active LLM profile.
• OpenAI API key is not configured. Set it in Settings > Catal

AI-assisted analysis of HKUDS/DeepTutor@3e82f13042 (2026-08-27). Data as JSON: /api/errors/c0340358c646b0f9. Report an issue: GitHub.