{"record":{"id":"09cfb8226fec57fc","repo":"docling-project/docling","slug":"response-schema-mismatch-client-and-server-versi","errorCode":null,"errorMessage":"Response schema mismatch — client and server versions may differ.","messagePattern":"Response schema mismatch — client and server versions may differ\\.","errorType":"exception","errorClass":"ResponseSchemaMismatchError","httpStatus":null,"severity":"error","filePath":"docling/service_client/client.py","lineNumber":280,"sourceCode":"            poll_server_wait if poll_client_interval is None else poll_client_interval\n        )\n        self._job_timeout = job_timeout\n        self._max_concurrency = self._validate_concurrency(\n            max_concurrency, name=\"max_concurrency\"\n        )\n        self._http_retries = http_retries\n        self._http_connect_timeout = http_connect_timeout\n        self._http_read_timeout = http_read_timeout\n\n    def _parse_result_model_response(\n        self,\n        response: httpx.Response,\n        model_cls: type[_T],\n    ) -> _T:\n        try:\n            return model_cls.model_validate_json(response.text)\n        except (ValidationError, ValueError) as exc:\n            raise ResponseSchemaMismatchError(\n                \"Response schema mismatch — client and server versions may differ.\",\n                status_code=response.status_code,\n                detail=str(exc),\n            ) from exc\n\n    def _serialize_convert_options(\n        self,\n        options: ConvertDocumentsRequestOptions,\n    ) -> dict[str, Any]:\n        return options.model_dump(\n            mode=\"json\",\n            exclude_defaults=True,\n            exclude_none=True,\n        )\n\n    @staticmethod\n    def _form_encode_options(data: dict[str, Any]) -> dict[str, Any]:\n        \"\"\"Make option values safe for ``multipart/form-data`` submission.","sourceCodeStart":262,"sourceCodeEnd":298,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/service_client/client.py#L262-L298","documentation":"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.","triggerScenarios":"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.","commonSituations":"See trigger scenarios.","solutions":["Align versions: upgrade/downgrade the docling client to match the docling-serve deployment.","Inspect response.text in the exception detail to see what the server actually returned.","If a proxy/gateway intercepts responses, bypass it or fix its rewrite rules.","After upgrading the server, restart clients so all instances use matching schemas."],"exampleFix":"# before\npip install docling==2.x  # client older than docling-serve 0.x with new schema\nresult = client.convert_file(f)  # ResponseSchemaMismatchError\n\n# after\npip install 'docling==<version matching docling-serve>'\nresult = client.convert_file(f)","handlingStrategy":"try-catch","validationCode":"import httpx, json\n\ndef server_returns_json(url: str) -> bool:\n    r = httpx.get(url.rstrip('/') + '/health')\n    ct = r.headers.get('content-type', '')\n    return 'json' in ct and r.status_code < 500","typeGuard":null,"tryCatchPattern":"from docling.service_client.exceptions import ResponseSchemaMismatchError\n\ntry:\n    result = client.convert_file(f)\nexcept ResponseSchemaMismatchError as e:\n    raise RuntimeError('client/server docling version mismatch — align versions') from e","preventionTips":["Pin client docling to the same release line as docling-serve.","Coordinate upgrades: upgrade server and clients together.","Ensure no proxy rewrites JSON responses."],"tags":["service-client","schema","version-mismatch","validation"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}