docling-project/docling · error · RuntimeError

gRPC metadata call failed for model {self.model_name}: {exc}

Error message

gRPC metadata call failed for model {self.model_name}: {exc}

What it means

Raised as RuntimeError by KserveV2GrpcClient.get_model_metadata wrapping a grpc.RpcError from the ModelMetadata RPC. The underlying RpcError (UNAVAILABLE, DEADLINE_EXCEEDED, NOT_FOUND, UNAUTHENTICATED, ...) is included in the message and chained as __cause__.

Source

Thrown at docling/models/inference_engines/common/kserve_v2_grpc.py:249

        except Exception:
            pass

    def close(self) -> None:
        self._channel.close()

    def get_model_metadata(self) -> KserveV2ModelMetadataResponse:
        request = service_pb2.ModelMetadataRequest(name=self.model_name)
        if self.model_version:
            request.version = self.model_version

        try:
            response = self._stub.ModelMetadata(
                request,
                timeout=self.timeout,
                metadata=self._grpc_metadata,
            )
        except grpc.RpcError as exc:
            raise RuntimeError(
                f"gRPC metadata call failed for model {self.model_name}: {exc}"
            ) from exc

        inputs = [
            KserveV2ModelTensorSpec(
                name=input_tensor.name,
                datatype=input_tensor.datatype,
                shape=[int(dim) for dim in input_tensor.shape],
            )
            for input_tensor in response.inputs
        ]
        outputs = [
            KserveV2ModelTensorSpec(
                name=output_tensor.name,
                datatype=output_tensor.datatype,
                shape=[int(dim) for dim in output_tensor.shape],
            )
            for output_tensor in response.outputs

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Read the gRPC status in the message (code + details) — UNAVAILABLE means connectivity/URL, NOT_FOUND means model name/version, DEADLINE_EXCEEDED means raise timeout.
2. Check base_url points at the gRPC port (commonly 8033/443 for KServe, not the HTTP 8080) and use_tls matches the server.
3. Verify the model_name/model_version against the server's model registry and retry once the server is healthy.

Example fix

# before
client = KserveV2GrpcClient(base_url='http://mysvc:8080', ...)  # HTTP port -> UNAVAILABLE

# after
client = KserveV2GrpcClient(base_url='mysvc:8033', use_tls=False, ...)  # gRPC port

from urllib.parse import urlsplit
u = urlsplit('//' + base_url)
assert u.port, 'base_url must include the gRPC port'
assert model_name, 'model_name required before metadata call'

import time
for attempt in range(3):
    try:
        meta = client.get_model_metadata()
        break
    except RuntimeError as e:
        if 'UNAVAILABLE' in str(e) and attempt < 2:
            time.sleep(2 ** attempt)
            continue
        raise

When it happens

Trigger: The gRPC call to the KServe ModelMetadata endpoint fails: server down/unreachable, wrong base_url, TLS mismatch, timeout, unknown model name/version, or missing auth metadata.

Common situations: Wrong endpoint URL or port (HTTP port vs gRPC port); self-signed cert with use_tls misconfigured; server pod not ready; model_version set to a nonexistent version; expired auth token in metadata.

Related errors

• Unsupported KServe request parameter integer range for gRPC:
• Unsupported KServe request parameter type for gRPC: key={key
• Unsupported numpy dtype for gRPC inline (non-binary) encodin
• Unsupported numpy dtype for gRPC inline (non-binary) decodin
• gRPC transport requires the 'remote-serving' extras. Install

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