PaddlePaddle/PaddleOCR · error · ResponseFormatError

Response body must be a JSON object.

Error message

Response body must be a JSON object.

What it means

Error "Response body must be a JSON object." thrown in PaddlePaddle/PaddleOCR.

Source

Thrown at paddleocr/_api_client/_http.py:62

def _extract_api_message(response: requests.Response) -> str:
    try:
        payload = response.json()
    except ValueError:
        return response.text
    if isinstance(payload, dict):
        msg = extract_api_message_from_payload(payload)
        if msg:
            return msg
    return response.text


def _response_json(response: requests.Response) -> Dict[str, Any]:
    try:
        payload = response.json()
    except ValueError as e:
        raise ResponseFormatError(f"Response body is not valid JSON: {e}") from e
    if not isinstance(payload, dict):
        raise ResponseFormatError("Response body must be a JSON object.")
    return payload


def _response_data(response: requests.Response) -> Dict[str, Any]:
    payload = _response_json(response)
    return unwrap_api_response(payload, response.status_code)


def _job_id_from_response(response: requests.Response) -> str:
    return extract_job_id(_response_data(response))


class HTTPClient:
    def __init__(
        self,
        token: str,
        base_url: str,
        timeout: float,

View on GitHub (pinned to 2661c7c0ef)

Solutions

1. Ensure the API endpoint returns a JSON object at the top level, not a list or scalar.
2. Check the base URL and API path; a wrong endpoint may return a JSON array or plain value.
3. Inspect the parsed payload to see what the server returned instead of an object.

Example fix

payload = response.json()
if not isinstance(payload, dict):
    print(payload)  # inspect unexpected JSON shape

When it happens

Trigger: Raised by _response_json() when the response is valid JSON but the top-level value is not an object (dict).

Common situations: The parsed JSON body was not an object (e.g., an array or scalar). Indicates an unexpected endpoint or API change. Verify the request URL and API version.

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