docling-project/docling · error · RuntimeError

KServe v2 client is not initialized.

Error message

KServe v2 client is not initialized.

What it means

The engine tried to resolve input/output tensor names from model metadata but the internal KServe v2 client (_kserve_client) is None, meaning initialize() has not completed (or failed before creating the client). Docling lazily creates the client during initialization, so any name resolution before that is a programming-order error.

Source

Thrown at docling/models/inference_engines/image_classification/api_kserve_v2_engine.py:72

        if not enable_remote_services:
            raise OperationNotAllowed(
                "Connections to remote services are only allowed when set explicitly. "
                "pipeline_options.enable_remote_services=True."
            )

    def _resolve_model_name(self) -> str:
        if self.options.model_name:
            return self.options.model_name

        return self._repo_id.replace("/", "--")

    def _resolve_model_version(self) -> Optional[str]:
        return self.options.model_version

    def _resolve_tensor_names(self) -> tuple[str, str]:
        if self._kserve_client is None:
            raise RuntimeError("KServe v2 client is not initialized.")

        metadata = self._kserve_client.get_model_metadata()
        if not metadata.inputs:
            raise RuntimeError(
                f"Expected image-classification model metadata to expose at least 1 input, "
                f"got {len(metadata.inputs)} inputs."
            )
        if not metadata.outputs:
            raise RuntimeError(
                f"Expected image-classification model metadata to expose at least 1 output, "
                f"got {len(metadata.outputs)} outputs."
            )

        input_name = metadata.inputs[0].name
        output_name = metadata.outputs[0].name
        return input_name, output_name

    def initialize(self) -> None:

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Call engine.initialize() and let it raise on connection failure before any inference; do not swallow initialization exceptions.
2. If the failure persists, check that the KServe endpoint URL/inference_url is reachable and credentials are valid so client creation succeeds.
3. Do not call the engine after close(); create a fresh engine instance instead.

Example fix

# before
engine = ApiKserveV2ImageClassificationEngine(...)
results = engine.predict_batch(batch)  # client is None

# after
engine = ApiKserveV2ImageClassificationEngine(...)
engine.initialize()
results = engine.predict_batch(batch)

if getattr(engine, "_kserve_client", None) is None or not engine._initialized:
    raise RuntimeError("engine not ready — call initialize() first")

try:
    engine.initialize()
    engine.predict_batch(batch)
except RuntimeError as e:
    if "not initialized" in str(e) or "KServe v2 client" in str(e):
        engine.initialize()  # single recovery attempt
        engine.predict_batch(batch)
    else:
        raise

When it happens

Trigger: Calling _resolve_tensor_names (directly, or via predict_batch before initialize(), or after an initialize() that raised before client creation) on ApiKserveV2ImageClassificationEngine.

Common situations: Calling predict() on an engine whose initialize() raised earlier (e.g. unreachable endpoint) and the exception was swallowed; reusing an engine object after close(); custom orchestration code that skips initialize().

Related errors

• Engine not initialized. Call initialize() first.
• KServe v2 client is not initialized.
• Engine not initialized. Call initialize() first.
• Engine not initialized. Call initialize() first.
• Engine not initialized. Call initialize() first.

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