{"record":{"id":"78bfa799a93dd555","repo":"docling-project/docling","slug":"expected-onnxruntimeimageclassificationengineoptio","errorCode":null,"errorMessage":"Expected OnnxRuntimeImageClassificationEngineOptions, got {type(options)}","messagePattern":"Expected OnnxRuntimeImageClassificationEngineOptions, got (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/image_classification/factory.py","lineNumber":44,"sourceCode":"    enable_remote_services: bool = False,\n    accelerator_options: AcceleratorOptions,\n    artifacts_path: Optional[Union[Path, str]] = None,\n) -> BaseImageClassificationEngine:\n    \"\"\"Factory to create image-classification engines.\"\"\"\n    model_config: Optional[EngineModelConfig] = None\n    if model_spec is not None:\n        model_config = model_spec.get_engine_config(options.engine_type)\n\n    if options.engine_type == ImageClassificationEngineType.ONNXRUNTIME:\n        from docling.datamodel.image_classification_engine_options import (\n            OnnxRuntimeImageClassificationEngineOptions,\n        )\n        from docling.models.inference_engines.image_classification.onnxruntime_engine import (\n            OnnxRuntimeImageClassificationEngine,\n        )\n\n        if not isinstance(options, OnnxRuntimeImageClassificationEngineOptions):\n            raise ValueError(\n                \"Expected OnnxRuntimeImageClassificationEngineOptions, \"\n                f\"got {type(options)}\"\n            )\n\n        return OnnxRuntimeImageClassificationEngine(\n            options=options,\n            model_config=model_config,\n            artifacts_path=artifacts_path,\n            accelerator_options=accelerator_options,\n        )\n\n    if options.engine_type == ImageClassificationEngineType.TRANSFORMERS:\n        from docling.datamodel.image_classification_engine_options import (\n            TransformersImageClassificationEngineOptions,\n        )\n        from docling.models.inference_engines.image_classification.transformers_engine import (\n            TransformersImageClassificationEngine,\n        )","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/image_classification/factory.py#L26-L62","documentation":"The image-classification engine factory dispatches on options.engine_type, and for EngineType.ONNXRUNTIME the options object must be OnnxRuntimeImageClassificationEngineOptions. Passing an options instance belonging to a different engine (with engine_type=ONNXRUNTIME) indicates inconsistent construction — usually engine_type was mutated after the options object was created.","triggerScenarios":"Calling the factory's create function with options whose .engine_type == ImageClassificationEngineType.ONNXRUNTIME but whose concrete class is not OnnxRuntimeImageClassificationEngineOptions — e.g. manually setting engine_type on a Transformers options object.","commonSituations":"Copying a base/default options object and flipping only the engine_type field; config files deserialized into a generic options class with a stale engine_type; mixing option classes during a migration between engine backends.","solutions":["Construct the matching options class: OnnxRuntimeImageClassificationEngineOptions() — its engine_type is already correct; do not override engine_type manually.","If building options from a model spec/config, make sure get_engine_config returns the class tied to the declared engine_type.","Audit code for assignments like options.engine_type = ... and replace them with instantiation of the proper options subclass."],"exampleFix":"# before\noptions = TransformersImageClassificationEngineOptions()\noptions.engine_type = ImageClassificationEngineType.ONNXRUNTIME  # mismatch\n\n# after\nfrom docling.datamodel.image_classification_engine_options import OnnxRuntimeImageClassificationEngineOptions\noptions = OnnxRuntimeImageClassificationEngineOptions()","handlingStrategy":"type-guard","validationCode":"from docling.datamodel.image_classification_engine_options import OnnxRuntimeImageClassificationEngineOptions\n\nif not isinstance(options, OnnxRuntimeImageClassificationEngineOptions):\n    options = OnnxRuntimeImageClassificationEngineOptions(**options.model_dump())","typeGuard":"def is_onnx_options(options) -> TypeGuard[OnnxRuntimeImageClassificationEngineOptions]:\n    return isinstance(options, OnnxRuntimeImageClassificationEngineOptions)","tryCatchPattern":"try:\n    engine = create_engine(options=options, ...)\nexcept ValueError as e:\n    if \"Expected OnnxRuntimeImageClassificationEngineOptions\" in str(e):\n        options = OnnxRuntimeImageClassificationEngineOptions()\n        engine = create_engine(options=options, ...)\n    else:\n        raise","preventionTips":["Never assign engine_type on an existing options object; instantiate the right class.","Use TypeGuard checks before factory calls when options arrive from dynamic config.","Derive engine_type from the options instance rather than a separate field."],"tags":["factory","options-mismatch","configuration","onnx"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}