docling-project/docling · error · RuntimeError

Engine not initialized

Error message

Engine not initialized

What it means

The VLM picture-description model generates descriptions through self.engine (a local vision-language engine built on transformers). If the engine was never constructed (model built without a successful init), _annotate_images raises this RuntimeError as soon as a batch of images is submitted.

Source

Thrown at docling/models/stages/picture_description/picture_description_vlm_engine_model.py:163

                temperature=float(temperature),
                max_new_tokens=int(max_new_tokens),
                stop_strings=stop_strings,
                extra_generation_config=extra_generation_config,
            )
            for image in image_list
        ]

    def _annotate_images(self, images: Iterable[Image.Image]) -> Iterable[str]:
        """Generate descriptions for a batch of images.

        Args:
            images: Iterable of PIL images to describe

        Yields:
            Description text for each image
        """
        if self.engine is None:
            raise RuntimeError("Engine not initialized")

        # Convert to list for batch processing
        # TODO: Consider using chunking here
        image_list = list(images)

        if not image_list:
            return

        try:
            # Prepare batch of engine inputs
            engine_inputs = self._build_engine_inputs(image_list)

            # Generate descriptions using batch prediction
            outputs = self.engine.predict_batch(engine_inputs)

            # Extract and yield descriptions
            for output in outputs:
                description = output.text.strip()

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Construct the model through the normal factory path with enabled=True and a valid artifacts_path so the engine is created in __init__.
2. Guard calls: skip annotation when the model is disabled instead of invoking _annotate_images.
3. Log/inspect model.engine right after construction to confirm initialization succeeded.

Example fix

# before
model = PictureDescriptionVlmModel(enabled=False)
model._annotate_images(images)  # RuntimeError

# after
model = PictureDescriptionVlmModel(enabled=True, artifacts_path=path)
descs = model._annotate_images(images) if model.engine else []

if vlm_model.engine is None:
    raise RuntimeError("VLM engine not loaded — construct with enabled=True and valid artifacts_path")

def vlm_ready(model) -> bool:
    return model.engine is not None

try:
    descriptions = list(vlm_model._annotate_images(images))
except RuntimeError as e:
    if "Engine not initialized" in str(e):
        log.warning("VLM unavailable; skipping picture descriptions")
        descriptions = [""] * len(images)
    else:
        raise

When it happens

Trigger: Calling the model's annotation path (directly or via a pipeline run with picture description enabled) on an instance whose engine is None — typically constructed disabled or via a path that skipped engine loading.

Common situations: Programmatic construction without artifacts; test stubs; an exception during engine init being swallowed by custom glue code; calling internal methods on a half-initialized model.

Related errors

• Picture classifier engine is not initialized.
• transformers >=4.46 is not installed. Please install Docling
• {pipeline_name} does not support ThreadedDoclingParseDocumen
• The parameters vlm_pipeline_model, vlm_pipeline_model_local
• Cannot specify both vlm_pipeline_preset and vlm_pipeline_cus

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