docling-project/docling · error · RuntimeError

Engine not initialized. Call initialize() first.

Error message

Engine not initialized. Call initialize() first.

What it means

OnnxRuntimeObjectDetectionEngine.predict_batch() raises RuntimeError('Engine not initialized. Call initialize() first.') when self._session or self._processor is None. The ONNX InferenceSession and HF processor are created during initialize(), and inference is refused before both exist.

Source

Thrown at docling/models/inference_engines/object_detection/onnxruntime_engine.py:171

                device,
            )
        return ["CPUExecutionProvider"]

    def predict_batch(
        self, input_batch: List[ObjectDetectionEngineInput]
    ) -> List[ObjectDetectionEngineOutput]:
        """Run inference on a batch of inputs.

        Args:
            input_batch: List of input images with metadata

        Returns:
            List of detection outputs
        """
        if not input_batch:
            return []
        if self._session is None or self._processor is None:
            raise RuntimeError("Engine not initialized. Call initialize() first.")

        # Preprocess images using HF processor (source of truth)
        images = [item.image.convert("RGB") for item in input_batch]
        inputs = self._processor(images=images, return_tensors="np")

        # Get original sizes for post-processing
        orig_sizes = np.array(
            [[img.width, img.height] for img in images], dtype=np.int64
        )

        # Run ONNX inference
        output_tensors = self._session.run(
            None,
            {
                "images": inputs["pixel_values"],
                "orig_target_sizes": orig_sizes,
            },
        )

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Call engine.initialize() immediately after construction and before any predict_batch().
2. Prefer the standard DocumentConverter pipeline, which manages engine initialization.
3. If init already ran, inspect earlier logs — the underlying failure (e.g. FileNotFoundError for the model) is the real problem.

Example fix

# before
engine = OnnxRuntimeObjectDetectionEngine(options=opts, ...)
outs = engine.predict_batch(inputs)

# after
engine = OnnxRuntimeObjectDetectionEngine(options=opts, ...)
engine.initialize()
outs = engine.predict_batch(inputs)

if engine._session is None or engine._processor is None:
    engine.initialize()

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

When it happens

Trigger: Calling predict_batch() without a prior successful initialize(); or initialize() failed (missing model file, bad onnxruntime install) and the exception was swallowed before predict was attempted.

Common situations: Custom orchestration bypassing the standard pipeline; engine reuse after a crashed init; threading issues where one thread inits while another predicts.

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.
• KServe v2 client is not initialized.

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