docling-project/docling · error · RuntimeError

Engine not initialized

Error message

Engine not initialized

What it means

The VLM code/formula stage requires a loaded inference engine; it stores it on self.engine during initialization. If __call__ runs with self.engine still None — typically because the model was constructed with enabled=False and later called directly, or initialization failed/was skipped — this RuntimeError aborts batch processing. It is a lifecycle misuse error, not a data error.

Source

Thrown at docling/models/stages/code_formula/code_formula_vlm_model.py:241

        doc: DoclingDocument,
        element_batch: Iterable[ItemAndImageEnrichmentElement],
    ) -> Iterable[NodeItem]:
        """Process a batch of code/formula elements.

        Args:
            doc: The document being processed
            element_batch: Batch of elements to process

        Yields:
            Enriched elements with extracted text
        """
        if not self.enabled:
            for element in element_batch:
                yield element.item
            return

        if self.engine is None:
            raise RuntimeError("Engine not initialized")

        labels: List[str] = []
        images: List[Union[Image.Image, np.ndarray]] = []
        elements: List[Union[CodeItem, TextItem]] = []

        for el in element_batch:
            assert isinstance(el.item, CodeItem | TextItem)
            elements.append(el.item)
            labels.append(el.item.label)
            images.append(el.image)

        # Process batch through engine
        try:
            # Prepare batch of engine inputs
            engine_inputs = [
                VlmEngineInput(
                    image=image
                    if isinstance(image, Image.Image)

View on GitHub (pinned to 61d76f1ff3)

Solutions

1. Ensure the model is constructed with enabled=True and a valid artifacts path so the engine loads during __init__.
2. Re-instantiate the model after changing enablement/options instead of mutating flags on an existing instance.
3. In tests, gate direct calls on model.enabled and engine presence: if not model.enabled, skip or pass elements through.

Example fix

# before
model = CodeFormulaVlmModel(enabled=False, ...)
for out in model(ctx, doc, batch):  # RuntimeError: Engine not initialized
    ...

# after
model = CodeFormulaVlmModel(enabled=True, artifacts_path=path, ...)
for out in model(ctx, doc, batch):
    ...

if model.enabled and model.engine is not None:
    results = model(ctx, doc, batch)
else:
    results = (el.item for el in batch)  # pass-through like the disabled path

try:
    for out in model(ctx, doc, batch):
        process(out)
except RuntimeError as err:
    if "Engine not initialized" in str(err):
        raise RuntimeError("Model was built disabled; construct with enabled=True") from err
    raise

When it happens

Trigger: Constructing the model with enabled=False (or artifacts path invalid) so the engine is never created, then bypassing the enabled guard by calling the processing method directly; or a partial __init__ failure that left engine unset.

Common situations: Testing code that instantiates the model disabled but calls the batch method anyway; toggling options.enabled after construction without re-initializing; refactors that moved engine creation out of __init__.

Related errors

• Label must be either code or formula
• Cannot convert doc with {self.document_hash} because the bac
• Cannot convert EPUB with hash {self.document_hash} because t
• Invalid HTML document.
• The parameters vlm_pipeline_model, vlm_pipeline_model_local

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