PaddlePaddle/PaddleOCR · error · ResponseFormatError

Unknown or missing job state: {state}

Error message

Unknown or missing job state: {state}

What it means

Raised as ResponseFormatError by validate_state() when the job-status payload's 'state' field is missing or outside {pending, running, done, failed}. It signals an unexpected response body from the service, not a job failure.

Source

Thrown at paddleocr/_api_client/_core.py:122

def extract_api_message_from_payload(payload: dict) -> Optional[str]:
    for key in ("msg", "errorMsg", "message"):
        value = payload.get(key)
        if value:
            return str(value)
    data = payload.get("data")
    if isinstance(data, dict):
        value = data.get("errorMsg")
        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,

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Log the raw response body to see what 'state' actually contained.
2. Upgrade the paddleocr package to a version matching the current service API.
3. If a proxy/gateway intercepts responses, bypass it or fix its error format.
4. Retry the status call once; a transient malformed response can occur under load.

from paddleocr._api_client.errors import ResponseFormatError
try:
    status = await client.get_status(job_id)
except ResponseFormatError as e:
    log.error("unexpected status payload: %s", e)
    # one retry, then surface; likely version drift or gateway interference

When it happens

Trigger: Any status poll (wait loop, get_status) where data.get('state') is None, a new state string introduced server-side, or a payload that is not the expected job-status dict (e.g. an error envelope).

Common situations: Service API version drift adding new states, gateway/HTML error pages parsed as JSON, or unwrapped payloads where the data envelope changed.

Related errors

• 'extractProgress' must be an object.
• 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/40c89fbc3dc2394f. Report an issue: GitHub.