{"record":{"id":"fa472ccc52f72072","repo":"docling-project/docling","slug":"model-not-loaded-ensure-enginemodelconfig-was-pro","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/mlx_engine.py","lineNumber":171,"sourceCode":"        processing is done sequentially. This method is provided for API\n        consistency but does not provide performance benefits over sequential\n        processing.\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.vlm_model is None or self.processor is None or self.config is None:\n            raise RuntimeError(\n                \"Model not loaded. Ensure EngineModelConfig was provided during initialization.\"\n            )\n\n        _log.debug(\n            f\"MLX runtime processing batch of {len(input_batch)} images sequentially \"\n            \"(MLX does not support batched inference)\"\n        )\n\n        outputs: List[VlmEngineOutput] = []\n\n        # MLX models are not thread-safe - use global lock to serialize access\n        with _MLX_GLOBAL_LOCK:\n            _log.debug(\"MLX model: Acquired global lock for thread safety\")\n\n            for input_data in input_batch:\n                # Preprocess image\n                images = preprocess_image_batch([input_data.image])\n                image = images[0]","sourceCodeStart":153,"sourceCodeEnd":189,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/vlm/mlx_engine.py#L153-L189","documentation":"MlxVlmEngine.predict_batch() asserts that initialize() actually loaded a model, processor, and config. These are only populated when model_config with a repo_id was supplied at construction; an engine created without them has nothing to run inference with, so this RuntimeError fires.","triggerScenarios":"Constructing MlxVlmEngine without model_config (or with model_config.repo_id None), then calling predict_batch on a non-empty batch — initialize() returns without loading and the vlm_model/processor/config check fails.","commonSituations":"Assuming the engine pulls a default model on its own; wiring an options-only pipeline where the model spec was never attached; passing model_spec=None through create_vlm_engine.","solutions":["Provide an EngineModelConfig with a repo_id (or a VlmModelSpec through the factory) so initialize() downloads and loads the model","Verify model_config is not None and model_config.repo_id is set before running predictions","Check the engine's constructor arguments — MLX has no bundled default weights"],"exampleFix":"# before\nengine = MlxVlmEngine(options=MlxVlmEngineOptions())  # no model_config\noutputs = engine.predict_batch(inputs)  # RuntimeError\n\n# after\nengine = MlxVlmEngine(\n    options=MlxVlmEngineOptions(),\n    model_config=EngineModelConfig(repo_id='ds4sd/SmolDocling-256M-preview', revision='main'),\n)\noutputs = engine.predict_batch(inputs)","handlingStrategy":"validation","validationCode":"engine = MlxVlmEngine(options=opts, model_config=model_config, artifacts_path=None)\nassert model_config is not None and model_config.repo_id, 'MLX engine requires EngineModelConfig.repo_id'\nengine.initialize()  # force load; fail fast here, not mid-batch\nassert engine.vlm_model is not None and engine.processor is not None and engine.config 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 MLX engine before inference') from e\n    raise","preventionTips":["Always construct VLM engines with a model spec; there is no default model","Call engine.initialize() eagerly after construction to surface config errors at startup","Add a smoke-test inference of one image in CI to catch missing-model wiring"],"tags":["vlm","mlx","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"}