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 ONNX Runtime engine before initialize() completed. The guard checks that _session, _processor, _input_name, and _output_name are all set; any None means initialization never ran or failed partway, and inference would otherwise crash with an opaque AttributeError.

Source

Thrown at docling/models/inference_engines/image_classification/onnxruntime_engine.py:166

            _log.warning(
                "Unsupported ONNX device '%s' for image classification. Falling back to CPU provider.",
                device,
            )
        return ["CPUExecutionProvider"]

    def predict_batch(
        self, input_batch: List[ImageClassificationEngineInput]
    ) -> List[ImageClassificationEngineOutput]:
        """Run inference on a batch of inputs."""
        if not input_batch:
            return []
        if (
            self._session is None
            or self._processor is None
            or self._input_name is None
            or self._output_name is None
        ):
            raise RuntimeError("Engine not initialized. Call initialize() first.")

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

        output_tensors = self._session.run(
            [self._output_name],
            {
                self._input_name: input_tensor,
            },
        )

        if len(output_tensors) < 1:
            raise RuntimeError(
                "Expected ONNX model to return at least 1 output containing logits"
            )

        logits_batch = np.asarray(output_tensors[0], dtype=np.float32)

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Call engine.initialize() exactly once before the first predict_batch and let its errors propagate.
2. Diagnose any earlier initialize() failure (missing ONNX file, no graph inputs/outputs) instead of continuing past it.
3. Wrap engine usage in a lifecycle that guarantees init-then-predict ordering.

Example fix

# before
engine = OnnxRuntimeImageClassificationEngine(...)
engine.predict_batch(batch)  # session is None

# after
engine = OnnxRuntimeImageClassificationEngine(...)
engine.initialize()
engine.predict_batch(batch)

if any(getattr(engine, attr, None) is None for attr in ("_session", "_processor", "_input_name", "_output_name")):
    engine.initialize()

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 OnnxRuntimeImageClassificationEngine.predict_batch() when any of _session/_processor/_input_name/_output_name is None — initialize() skipped, failed (e.g. model file missing, graph invalid), or the engine was used after an init exception was suppressed.

Common situations: Retry wrappers that swallow initialize() failures and continue; custom pipelines that construct the engine but forget init; reusing an engine after an OOM or load failure cleared its session.

Related errors

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

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