docling-project/docling · error · RuntimeError

Engine not initialized. Call initialize() first.

Error message

Engine not initialized. Call initialize() first.

What it means

predict_batch() on the KServe v2 engine raises RuntimeError when self._initialized is False. The engine performs expensive setup (HF processor download, KServe client construction, tensor-name discovery) in initialize(), and refuses to run inference before that completes.

Source

Thrown at docling/models/inference_engines/object_detection/api_kserve_v2_engine.py:173

        self._initialized = True
        _log.info(
            "KServe v2 object-detection engine ready (inputs=[%s, %s], outputs=[%s, %s, %s])",
            self._input_images_name,
            self._input_orig_target_sizes_name,
            self._output_labels_name,
            self._output_boxes_name,
            self._output_scores_name,
        )

    def predict_batch(
        self, input_batch: List[ObjectDetectionEngineInput]
    ) -> List[ObjectDetectionEngineOutput]:
        """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_images_name is not None
        assert self._input_orig_target_sizes_name is not None
        assert self._output_labels_name is not None
        assert self._output_boxes_name is not None
        assert self._output_scores_name is not None

        if _log.isEnabledFor(logging.DEBUG):
            _t_preproc_start = time.time()
            _t_preproc_mono = time.monotonic()
        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"])
        orig_sizes = np.asarray(

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Call engine.initialize() before predict_batch() (the standard pipeline does this for you — prefer using the pipeline API).
2. Guard with 'if not engine._initialized' style checks only internally; in application code simply always initialize right after construction.
3. Ensure initialize() exceptions propagate — never call predict after a failed init.

Example fix

# before
engine = ApiKserveV2ObjectDetectionEngine(options=opts, enable_remote_services=True)
results = engine.predict_batch(batch)

# after
engine = ApiKserveV2ObjectDetectionEngine(options=opts, enable_remote_services=True)
engine.initialize()
results = engine.predict_batch(batch)

if not getattr(engine, "_initialized", False):
    engine.initialize()
assert engine._initialized

try:
    engine.predict_batch(batch)
except RuntimeError as e:
    if "not initialized" in str(e):
        engine.initialize()
        outputs = engine.predict_batch(batch)  # retry once after real init
    else:
        raise

When it happens

Trigger: Calling engine.predict_batch(inputs) on a freshly constructed ApiKserveV2ObjectDetectionEngine without calling initialize(); or after initialize() raised and the caller ignored the failure.

Common situations: Manual engine lifecycle management in custom pipelines; retry wrappers that reconstruct the engine but skip initialization; async code paths where initialize() runs in another task that has not finished.

Related errors

• KServe v2 client is not initialized.
• 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/d9afd93d39c0aac9. Report an issue: GitHub.