{"record":{"id":"cbc35900fae36c5f","repo":"docling-project/docling","slug":"model-not-loaded-ensure-enginemodelconfig-was-pro-cbc359","errorCode":null,"errorMessage":"Model not loaded. Ensure EngineModelConfig was provided during initialization.","messagePattern":"Model not loaded\\. Ensure EngineModelConfig was provided during initialization\\.","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/vlm/vllm_engine.py","lineNumber":274,"sourceCode":"\n        This method processes multiple images in a single batched vLLM call,\n        which is much more efficient than processing them sequentially.\n\n        Args:\n            input_batch: List of inputs to process\n\n        Returns:\n            List of outputs, one per input\n        \"\"\"\n        if not self._initialized:\n            self.initialize()\n\n        if not input_batch:\n            return []\n\n        # Model should already be loaded via initialize()\n        if self.llm is None or self.processor is None or self.sampling_params is None:\n            raise RuntimeError(\n                \"Model not loaded. Ensure EngineModelConfig was provided during initialization.\"\n            )\n\n        # Preprocess images\n        images = preprocess_image_batch([inp.image for inp in input_batch])\n\n        # Get prompt style from first input's extra config\n        first_input = input_batch[0]\n        prompt_style = first_input.extra_generation_config.get(\n            \"transformers_prompt_style\",\n            TransformersPromptStyle.CHAT,\n        )\n\n        # Format prompts\n        prompts: List[str | None] = []\n        for input_data in input_batch:\n            formatted_prompt = format_prompt_for_vlm(\n                prompt=input_data.prompt,","sourceCodeStart":256,"sourceCodeEnd":292,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/vlm/vllm_engine.py#L256-L292","documentation":"VllmVlmEngine.predict_batch() asserts that initialize() built its LLM instance, processor, and SamplingParams. These are populated only when a model_config with a repo_id was provided; without one the engine initializes device handling but never constructs an LLM, and this RuntimeError fires on the first batch.","triggerScenarios":"Creating VllmVlmEngine without model_config (or model_spec=None through create_vlm_engine), then calling predict_batch on a non-empty input list.","commonSituations":"Options-only setup where the model spec is never attached; assuming vLLM launches a default model from the local HuggingFace cache automatically.","solutions":["Pass an EngineModelConfig with repo_id (or a VlmModelSpec through the factory) so initialize() builds the vLLM LLM","Check that model_config is not None and repo_id is set before the first predict_batch call","Note vLLM has no default model — an explicit repo is mandatory"],"exampleFix":"# before\nengine = VllmVlmEngine(options=VllmVlmEngineOptions())\noutputs = engine.predict_batch(inputs)  # RuntimeError\n\n# after\nengine = VllmVlmEngine(\n    options=VllmVlmEngineOptions(),\n    model_config=EngineModelConfig(repo_id='rednote-hilab/dots.mocr'),\n)\noutputs = engine.predict_batch(inputs)","handlingStrategy":"validation","validationCode":"engine = VllmVlmEngine(options=opts, model_config=model_config, artifacts_path=None, accelerator_options=acc)\nassert model_config is not None and model_config.repo_id, 'vLLM engine requires EngineModelConfig.repo_id'\nengine.initialize()\nassert engine.llm is not None and engine.processor is not None and engine.sampling_params is not None","typeGuard":null,"tryCatchPattern":"try:\n    outputs = engine.predict_batch(inputs)\nexcept RuntimeError as e:\n    if 'Model not loaded' in str(e):\n        raise SystemExit('Attach an EngineModelConfig(repo_id=...) to the vLLM engine before inference') from e\n    raise","preventionTips":["Always pass model_config with repo_id when building VllmVlmEngine — vLLM has no default model","Initialize eagerly at startup so missing-model errors surface before work is queued","Assert engine.llm is populated after initialize() in integration smoke tests"],"tags":["vlm","vllm","configuration","model-not-loaded","runtime-error"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}