docling-project/docling · error · ImportError

gRPC transport requires the 'remote-serving' extras. Install

Error message

gRPC transport requires the 'remote-serving' extras. Install with: pip install 'docling[remote-serving]'

What it means

Raised as ImportError by KserveV2GrpcClient.__post_init__ when the grpcio / KServe protobuf modules are not installed. The gRPC transport is an optional feature guarded behind the 'remote-serving' extras; instantiating the gRPC client without them fails fast.

Source

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

@dataclass
class KserveV2GrpcClient:
    """Minimal client for KServe v2 gRPC infer requests."""

    base_url: str
    model_name: str
    model_version: str | None
    timeout: float
    metadata: Mapping[str, str]
    use_tls: bool
    max_message_bytes: int
    use_binary_data: bool = True
    grpc_channel_args: List[Tuple[str, Any]] = field(default_factory=list)

    def __post_init__(self) -> None:
        if grpc is None or service_pb2 is None or service_pb2_grpc is None:
            raise ImportError(
                "gRPC transport requires the 'remote-serving' extras. "
                "Install with: pip install 'docling[remote-serving]'"
            )

        endpoint = _resolve_grpc_endpoint(
            base_url=self.base_url,
        )
        channel_options: List[Tuple[str, Any]] = [
            ("grpc.max_send_message_length", self.max_message_bytes),
            ("grpc.max_receive_message_length", self.max_message_bytes),
        ]
        channel_options.extend(self.grpc_channel_args)
        # dns:/// URLs rely on gRPC's DNS resolver returning multiple A records (e.g. headless k8s
        # services). Without a client-side lb policy, gRPC would pick just the first address.
        # Auto-inject round_robin unless the caller already specified a policy.
        if self.base_url.startswith("dns:///") and not any(
            k == "grpc.lb_policy_name" for k, _ in channel_options
        ):

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Install the extras: pip install 'docling[remote-serving]' (or add it via uv add 'docling[remote-serving]').
2. Verify the import works afterwards: python -c "import grpcio".
3. Alternatively switch the engine config to the HTTP transport, which needs no extras.

Example fix

# before: ImportError: gRPC transport requires the 'remote-serving' extras
# after:
# pip install 'docling[remote-serving]'
# or: uv add 'docling[remote-serving]'

try:
    import grpc  # noqa
    from docling.models.inference_engines.common import kserve_v2_grpc  # noqa
    grpc_ok = True
except ImportError:
    grpc_ok = False
if not grpc_ok:
    raise SystemError("install first: pip install 'docling[remote-serving]'")

def grpc_transport_available() -> bool:
    try:
        import grpc  # noqa: F401
        return True
    except ImportError:
        return False

When it happens

Trigger: Constructing KserveV2GrpcClient (e.g. configuring a remote inference engine with the gRPC transport) in an environment where docling was installed without the remote-serving extras.

Common situations: Installing docling-slim or plain docling and then enabling remote inference engines; CI environments with a minimal dependency set; upgrading docling and the extras were not carried over.

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 metadata call failed for model {self.model_name}: {exc}

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