PaddlePaddle/PaddleOCR · error · ResponseFormatError

'extractProgress' must be an object.

Error message

'extractProgress' must be an object.

What it means

Raised as ResponseFormatError by job_status_from_data() when the payload's 'extractProgress' field is truthy but not a JSON object (dict). The progress parser expects totalPages/extractedPages/startTime/endTime keys inside an object; any other shape aborts status parsing.

Source

Thrown at paddleocr/_api_client/_core.py:132

        if value:
            return str(value)
    return None


def validate_state(data: dict) -> str:
    state = data.get("state")
    if state not in {"pending", "running", "done", "failed"}:
        raise ResponseFormatError(f"Unknown or missing job state: {state}")
    return state


def job_status_from_data(job_id: str, data: dict) -> JobStatus:
    state = validate_state(data)
    progress = None
    ep = data.get("extractProgress")
    if ep:
        if not isinstance(ep, dict):
            raise ResponseFormatError("'extractProgress' must be an object.")
        progress = Progress(
            total_pages=ep.get("totalPages", 0),
            extracted_pages=ep.get("extractedPages", 0),
            start_time=ep.get("startTime"),
            end_time=ep.get("endTime"),
        )
    return JobStatus(
        job_id=job_id,
        state=state,
        progress=progress,
        result=data.get("resultUrl"),
        error_msg=data.get("errorMsg"),
    )


def raise_for_status(status_code: int, msg: str) -> None:
    if 200 <= status_code < 300:
        return

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Log the raw status payload to inspect the actual extractProgress value.
2. Update the package to match the service's response schema version.
3. Fix test doubles to return an object with totalPages/extractedPages/startTime/endTime.
4. Report the schema change if the live service sends a non-object progress field.

from paddleocr._api_client.errors import ResponseFormatError
try:
    status = await client.get_status(job_id)
except ResponseFormatError as e:
    if "extractProgress" in str(e):
        log.error("progress shape changed; raw payload needed")
        raise

When it happens

Trigger: get_status() or the poll loop receiving a status payload where extractProgress is a string, number, or list (e.g. a bare percentage integer).

Common situations: Service API changes that flatten or retype progress fields, or mock/test servers returning simplified payloads.

Related errors

• Unknown or missing job state: {state}
• Response body must be a JSON object.
• Token is required. Set PADDLEOCR_ACCESS_TOKEN or pass token
• Model ${model} is not a document parsing model.
• resourceUrl is required.

AI-assisted analysis of PaddlePaddle/PaddleOCR@2661c7c0ef (2026-08-14). Data as JSON: /api/errors/e90da8e0aa77227f. Report an issue: GitHub.