docling-project/docling · error · RuntimeError

Engine not initialized. Call initialize() first.

Error message

Engine not initialized. Call initialize() first.

What it means

TransformersObjectDetectionEngine.predict_batch() raises RuntimeError when self._model or self._processor is None, i.e. before initialize() has successfully loaded them. This mirrors the ONNX and KServe engines' lifecycle contract: construct, initialize, then predict.

Source

Thrown at docling/models/inference_engines/object_detection/transformers_engine.py:195

        )

    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
        """
        import torch

        if not input_batch:
            return []
        if self._model is None or self._processor is None:
            raise RuntimeError("Engine not initialized. Call initialize() first.")

        # Preprocess images using HF processor
        images = [item.image.convert("RGB") for item in input_batch]
        inputs = self._processor(images=images, return_tensors="pt").to(self._device)

        # Get target sizes for post-processing
        target_sizes = torch.tensor(
            [[img.height, img.width] for img in images], device=self._device
        )

        # Run inference
        with torch.inference_mode():
            outputs = self._model(**inputs)  # type: ignore[operator]

        # Post-process using HuggingFace processor
        results = self._processor.post_process_object_detection(  # type: ignore[attr-defined]
            outputs,
            target_sizes=target_sizes,  # type: ignore[arg-type]

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Call engine.initialize() before predict_batch().
2. Use the standard pipeline API which enforces the lifecycle.
3. Make initialize() failures fatal — do not call predict after any init exception.

Example fix

# before
engine = TransformersObjectDetectionEngine(options=opts, ...)
outs = engine.predict_batch(batch)

# after
engine = TransformersObjectDetectionEngine(options=opts, ...)
engine.initialize()
outs = engine.predict_batch(batch)

if engine._model 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() on an uninitialized engine, or after a failed initialize() whose exception was caught and ignored upstream.

Common situations: Custom code managing engines manually; lazy-init patterns that assume predict triggers initialization; error handlers that log-and-continue past init failures.

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/f09c94894bc410a1. Report an issue: GitHub.