docling-project/docling · error · RuntimeError

Engine not initialized. Call initialize() first.

Error message

Engine not initialized. Call initialize() first.

What it means

predict_batch was called on the ApiKserveV2 engine before successful initialization. The engine tracks an _initialized flag set at the end of initialize(); inference before that would dereference a None client/processor, so it fails fast with this guard. Unlike the metadata errors, this is purely a call-order problem on the client side.

Source

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

                grpc_channel_args=list(self.options.grpc_channel_args),
            )
        self._input_name, self._output_name = self._resolve_tensor_names()

        self._initialized = True
        _log.info(
            "KServe v2 image-classification engine ready (input=%s, output=%s)",
            self._input_name,
            self._output_name,
        )

    def predict_batch(
        self, input_batch: List[ImageClassificationEngineInput]
    ) -> List[ImageClassificationEngineOutput]:
        """Run inference on a batch of images against a KServe v2 endpoint."""
        if not input_batch:
            return []
        if not self._initialized:
            raise RuntimeError("Engine not initialized. Call initialize() first.")

        # Type narrowing: _initialized guarantees these are non-None
        assert self._processor is not None
        assert self._kserve_client is not None
        assert self._input_name is not None
        assert self._output_name is not None

        images = [item.image.convert("RGB") for item in input_batch]
        processed_inputs = self._processor(images=images, return_tensors="np")
        pixel_values = np.asarray(processed_inputs["pixel_values"])

        outputs = self._kserve_client.infer(
            inputs={self._input_name: pixel_values},
            output_names=[self._output_name],
            request_parameters=self.options.request_parameters,
        )
        try:
            logits_batch = outputs[self._output_name]

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Call engine.initialize() once and let failures propagate — do not catch-and-continue.
2. If initialization failed, fix the root cause (endpoint reachability, enable_remote_services, metadata) before predicting.
3. Track engine state explicitly: initialize immediately after construction, before any predict_batch call.

Example fix

# before
try:
    engine.initialize()
except Exception:
    pass  # swallowed
engine.predict_batch(batch)  # RuntimeError

# after
engine.initialize()  # failures surface here
engine.predict_batch(batch)

if not engine._initialized:
    engine.initialize()  # or raise, depending on your lifecycle policy

try:
    engine.predict_batch(batch)
except RuntimeError as e:
    if "not initialized" in str(e):
        engine.initialize()
        engine.predict_batch(batch)
    else:
        raise

When it happens

Trigger: Calling engine.predict_batch(input_batch) on ApiKserveV2ImageClassificationEngine when _initialized is False — i.e. initialize() never ran, or it raised partway (client, processor, or tensor-name resolution failed) and the exception was caught upstream.

Common situations: Swallowing an initialize() exception in retry logic and continuing to predict; reusing an engine after a failed re-initialization; integrating the engine in a custom runner that skips the init step.

Related errors

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

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