docling-project/docling · error · RuntimeError

Invalid metadata response from {self.model_metadata_url}: {e

Error message

Invalid metadata response from {self.model_metadata_url}: {exc}

What it means

The GET to the model metadata URL returned a body that failed KserveV2ModelMetadataResponse.model_validate - either not JSON (HTML error page) or JSON missing required fields (name, inputs with name/datatype/shape). The chained exception is the json/pydantic error. The client uses metadata to plan inference, so it aborts.

Source

Thrown at docling/models/inference_engines/common/kserve_v2_http.py:311

    def get_model_metadata(self) -> KserveV2ModelMetadataResponse:
        """Fetch model metadata from KServe v2 endpoint.

        Returns:
            Validated model metadata including inputs/outputs schema

        Raises:
            requests.exceptions.Timeout: If request exceeds timeout
            requests.exceptions.ConnectionError: If cannot connect to server
            requests.exceptions.HTTPError: If server returns error status
            RuntimeError: If response format is invalid
        """
        response = self._execute_http_request(self.model_metadata_url, method="GET")

        try:
            return KserveV2ModelMetadataResponse.model_validate(response.json())
        except Exception as exc:
            raise RuntimeError(
                f"Invalid metadata response from {self.model_metadata_url}: {exc}"
            ) from exc

    def infer(
        self,
        *,
        inputs: Mapping[str, np.ndarray],
        output_names: list[str],
        request_parameters: Optional[Mapping[str, Any]] = None,
    ) -> Dict[str, np.ndarray]:
        """Execute inference request against KServe v2 endpoint.

        Args:
            inputs: Mapping of input tensor names to numpy arrays
            output_names: List of expected output tensor names
            request_parameters: Optional KServe v2 request-level parameters

        Returns:

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. curl the metadata URL directly and read the body - fix whatever it actually returns (auth error, 404 HTML, wrong path)
2. Verify the URL shape: <base>/v2/models/<model_name> for KServe v2
3. Confirm the server really speaks KServe v2 protocol, not just gRPC/HTTP v1
4. Ensure auth headers/metadata reach the metadata request too

import requests

resp = requests.get(f"{base_url}/v2/models/{model_name}", timeout=timeout)
assert resp.status_code == 200, resp.status_code
body = resp.json()  # raises immediately if the body is HTML/error JSON
assert "inputs" in body and "name" in body, body

try:
    metadata = client.get_model_metadata()
except RuntimeError as e:
    if "Invalid metadata response" in str(e):
        raise  # inspect e.__cause__; fix URL/auth/server, do not ignore
    raise

When it happens

Trigger: base_url wrong so the metadata route 404s into an HTML page served with 200; an auth wall returning a JSON login payload instead of metadata; a v2-incompatible server lacking /v2/models/<m>; versions/inputs shape differing from the pydantic contract (e.g. shape entries neither int nor str).

Common situations: Pointing the client at a v1-only Triton or a KServe v1 endpoint; trailing-slash or path-join mistakes in base_url; proxies answering before the model server; model name typo producing an error body.

Related errors

• Binary KServe response from {response.url} did not include {
• Invalid binary inference response header from {response.url}
• Invalid inference response from {self.infer_url}: {exc}
• Unsupported numpy dtype for KServe v2 input: {tensor.dtype!s
• Unsupported KServe v2 output datatype: {raw_output.datatype}

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