opendatalab/MinerU · error · ValueError

max_concurrent_requests must be a positive integer

Error message

max_concurrent_requests must be a positive integer

What it means

ValueError raised in router.py during health-payload processing: max_concurrent_requests (defaulting to 0 if absent) parsed to zero or negative. Every healthy worker must advertise a positive concurrency capacity, so this value fails validation and the server is treated as unhealthy / the health refresh aborts. It indicates either a malformed/foreign health payload or a worker misconfiguration in versions that expose this as a setting.

Source

Thrown at mineru/cli/router.py:659

    def _update_server_from_health_payload(
        self,
        server: WorkerState,
        payload: dict[str, Any],
    ) -> None:
        protocol_version = payload.get("protocol_version")
        if protocol_version != API_PROTOCOL_VERSION:
            raise ValueError(
                f"Unsupported protocol_version={protocol_version}, expected {API_PROTOCOL_VERSION}"
            )

        server.queued_tasks = int(payload.get("queued_tasks", 0))
        server.processing_tasks = int(payload.get("processing_tasks", 0))
        server.completed_tasks = int(payload.get("completed_tasks", 0))
        server.failed_tasks = int(payload.get("failed_tasks", 0))
        server.max_concurrent_requests = int(payload.get("max_concurrent_requests", 0))
        if server.max_concurrent_requests <= 0:
            raise ValueError("max_concurrent_requests must be a positive integer")
        server.processing_window_size = max(
            MIN_HEALTHY_PROCESSING_WINDOW_SIZE,
            int(
                payload.get(
                    "processing_window_size",
                    MIN_HEALTHY_PROCESSING_WINDOW_SIZE,
                )
            ),
        )
        server.healthy = payload.get("status") == "healthy"
        server.last_error = (
            None if server.healthy else json.dumps(payload, ensure_ascii=False)
        )
        server.consecutive_health_failures = (
            0 if server.healthy else server.consecutive_health_failures + 1
        )

    async def _refresh_server(self, server: WorkerState) -> None:

View on GitHub (pinned to 4fe4bde114)

Solutions

1. curl the worker's /health endpoint directly and check that max_concurrent_requests is present and > 0.
2. Align router and worker versions so the health schema matches (this error often co-occurs with the protocol_version check).
3. Configure the worker's concurrency setting properly for your hardware (it derives from worker capacity in shipped versions — do not force it to 0).
4. Fix test doubles to include all required health fields with realistic positive values.

Example fix

# before (mock health)
{'status': 'healthy', 'protocol_version': API_PROTOCOL_VERSION}  # missing field -> defaults to 0 -> ValueError

# after
{'status': 'healthy', 'protocol_version': API_PROTOCOL_VERSION, 'max_concurrent_requests': 4,
 'queued_tasks': 0, 'processing_tasks': 0, 'completed_tasks': 0, 'failed_tasks': 0}

import httpx

def worker_health_is_valid(base_url: str) -> bool:
    p = httpx.get(f'{base_url}/health', timeout=5).json()
    return isinstance(p.get('max_concurrent_requests'), int) and p['max_concurrent_requests'] > 0

def is_valid_health_payload(p: dict) -> bool:
    return (
        isinstance(p, dict)
        and isinstance(p.get('max_concurrent_requests'), int)
        and p['max_concurrent_requests'] > 0
    )

try:
    router._update_server_from_health_payload(server, payload)
except ValueError as exc:
    if 'max_concurrent_requests' in str(exc):
        logger.error('worker %s reports invalid capacity — check version/schema of its health endpoint', server.base_url)
    raise

When it happens

Trigger: A worker whose /health omits max_concurrent_requests entirely (payload.get default 0) — e.g. an old-version worker or a mock; a misconfigured worker reporting 0 capacity; a hand-rolled service reusing the worker port; schema drift where the field was renamed between versions.

Common situations: Mock/test workers implementing only part of the health schema; version mismatches between router and worker; custom instrumentation accidentally overwriting the field.

Related errors

• {payload_name} must be a JSON object
• middle_json must be a dict.
• middle_json must contain a list field named pdf_info.
• Unknown process_mode: {process_mode}
• Unsupported office suffix: {file_suffix}

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