docling-project/docling · error · ResponseSchemaMismatchError

Response schema mismatch — client and server versions may di

Error message

Response schema mismatch — client and server versions may differ.

What it means

The sync service client validates every response body against its Pydantic model (e.g. TaskStatusResponse). If model_validate_json raises ValidationError/ValueError, the payload does not match the schema the client was compiled against, and ResponseSchemaMismatchError is raised, hinting that client and server versions differ. It protects callers from silently misparsed responses.

Source

Thrown at docling/service_client/client.py:280

            poll_server_wait if poll_client_interval is None else poll_client_interval
        )
        self._job_timeout = job_timeout
        self._max_concurrency = self._validate_concurrency(
            max_concurrency, name="max_concurrency"
        )
        self._http_retries = http_retries
        self._http_connect_timeout = http_connect_timeout
        self._http_read_timeout = http_read_timeout

    def _parse_result_model_response(
        self,
        response: httpx.Response,
        model_cls: type[_T],
    ) -> _T:
        try:
            return model_cls.model_validate_json(response.text)
        except (ValidationError, ValueError) as exc:
            raise ResponseSchemaMismatchError(
                "Response schema mismatch — client and server versions may differ.",
                status_code=response.status_code,
                detail=str(exc),
            ) from exc

    def _serialize_convert_options(
        self,
        options: ConvertDocumentsRequestOptions,
    ) -> dict[str, Any]:
        return options.model_dump(
            mode="json",
            exclude_defaults=True,
            exclude_none=True,
        )

    @staticmethod
    def _form_encode_options(data: dict[str, Any]) -> dict[str, Any]:
        """Make option values safe for ``multipart/form-data`` submission.

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Align versions: upgrade/downgrade the docling client to match the docling-serve deployment.
2. Inspect response.text in the exception detail to see what the server actually returned.
3. If a proxy/gateway intercepts responses, bypass it or fix its rewrite rules.
4. After upgrading the server, restart clients so all instances use matching schemas.

Example fix

# before
pip install docling==2.x  # client older than docling-serve 0.x with new schema
result = client.convert_file(f)  # ResponseSchemaMismatchError

# after
pip install 'docling==<version matching docling-serve>'
result = client.convert_file(f)

import httpx, json

def server_returns_json(url: str) -> bool:
    r = httpx.get(url.rstrip('/') + '/health')
    ct = r.headers.get('content-type', '')
    return 'json' in ct and r.status_code < 500

from docling.service_client.exceptions import ResponseSchemaMismatchError

try:
    result = client.convert_file(f)
except ResponseSchemaMismatchError as e:
    raise RuntimeError('client/server docling version mismatch — align versions') from e

When it happens

Trigger: Client library from a newer/older docling release talking to a docling-serve with a different API schema; server behind a proxy returning an HTML error page instead of JSON; API gateway injecting unexpected fields or wrapping responses; server downgrade/upgrade mid-session.

Common situations: See trigger scenarios.

Related errors

• submit_batch() requires either 'target' or 'targets'.
• submit_batch() received both 'target' and 'targets'; supply
• Unsupported URL scheme: '{scheme}'. Only http:// and https:/
• {name} must be between 1 and {MAX_CONCURRENCY_LIMIT}, got {v
• Cannot convert Box Note with hash {self.document_hash}: no '

AI-assisted analysis of docling-project/docling@61d76f1ff3 (2026-08-14). Data as JSON: /api/errors/09cfb8226fec57fc. Report an issue: GitHub.