{"record":{"id":"41d15d50d78f0f0a","repo":"docling-project/docling","slug":"grpc-transport-requires-the-remote-serving-extra","errorCode":null,"errorMessage":"gRPC transport requires the 'remote-serving' extras. Install with: pip install 'docling[remote-serving]'","messagePattern":"gRPC transport requires the 'remote-serving' extras\\. Install with: pip install 'docling\\[remote-serving\\]'","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/common/kserve_v2_grpc.py","lineNumber":193,"sourceCode":"\n\n@dataclass\nclass KserveV2GrpcClient:\n    \"\"\"Minimal client for KServe v2 gRPC infer requests.\"\"\"\n\n    base_url: str\n    model_name: str\n    model_version: str | None\n    timeout: float\n    metadata: Mapping[str, str]\n    use_tls: bool\n    max_message_bytes: int\n    use_binary_data: bool = True\n    grpc_channel_args: List[Tuple[str, Any]] = field(default_factory=list)\n\n    def __post_init__(self) -> None:\n        if grpc is None or service_pb2 is None or service_pb2_grpc is None:\n            raise ImportError(\n                \"gRPC transport requires the 'remote-serving' extras. \"\n                \"Install with: pip install 'docling[remote-serving]'\"\n            )\n\n        endpoint = _resolve_grpc_endpoint(\n            base_url=self.base_url,\n        )\n        channel_options: List[Tuple[str, Any]] = [\n            (\"grpc.max_send_message_length\", self.max_message_bytes),\n            (\"grpc.max_receive_message_length\", self.max_message_bytes),\n        ]\n        channel_options.extend(self.grpc_channel_args)\n        # dns:/// URLs rely on gRPC's DNS resolver returning multiple A records (e.g. headless k8s\n        # services). Without a client-side lb policy, gRPC would pick just the first address.\n        # Auto-inject round_robin unless the caller already specified a policy.\n        if self.base_url.startswith(\"dns:///\") and not any(\n            k == \"grpc.lb_policy_name\" for k, _ in channel_options\n        ):","sourceCodeStart":175,"sourceCodeEnd":211,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/common/kserve_v2_grpc.py#L175-L211","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install the extras: pip install 'docling[remote-serving]' (or add it via uv add 'docling[remote-serving]').","Verify the import works afterwards: python -c \"import grpcio\".","Alternatively switch the engine config to the HTTP transport, which needs no extras."],"exampleFix":"# before: ImportError: gRPC transport requires the 'remote-serving' extras\n# after:\n# pip install 'docling[remote-serving]'\n# or: uv add 'docling[remote-serving]'","handlingStrategy":"validation","validationCode":"try:\n    import grpc  # noqa\n    from docling.models.inference_engines.common import kserve_v2_grpc  # noqa\n    grpc_ok = True\nexcept ImportError:\n    grpc_ok = False\nif not grpc_ok:\n    raise SystemError(\"install first: pip install 'docling[remote-serving]'\")","typeGuard":"def grpc_transport_available() -> bool:\n    try:\n        import grpc  # noqa: F401\n        return True\n    except ImportError:\n        return False","tryCatchPattern":null,"preventionTips":["Declare 'docling[remote-serving]' in your project dependencies when using gRPC engines.","Fail fast at startup with a capability check instead of at first request.","Bake the extras into Docker images used for remote inference."],"tags":["kserve","grpc","import-error","extras","installation"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}