{"record":{"id":"7c665d4b1192eab9","repo":"docling-project/docling","slug":"expected-transformersimageclassificationengineopti","errorCode":null,"errorMessage":"Expected TransformersImageClassificationEngineOptions, got {type(options)}","messagePattern":"Expected TransformersImageClassificationEngineOptions, got (.+?)","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/image_classification/factory.py","lineNumber":65,"sourceCode":"            )\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        )\n\n        if not isinstance(options, TransformersImageClassificationEngineOptions):\n            raise ValueError(\n                \"Expected TransformersImageClassificationEngineOptions, \"\n                f\"got {type(options)}\"\n            )\n\n        return TransformersImageClassificationEngine(\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.API_KSERVE_V2:\n        from docling.datamodel.image_classification_engine_options import (\n            ApiKserveV2ImageClassificationEngineOptions,\n        )\n        from docling.models.inference_engines.image_classification.api_kserve_v2_engine import (\n            ApiKserveV2ImageClassificationEngine,\n        )","sourceCodeStart":47,"sourceCodeEnd":83,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/image_classification/factory.py#L47-L83","documentation":"The engine factory requires that a TRANSFORMERS engine_type be paired with a TransformersImageClassificationEngineOptions instance. The isinstance check fails when the options object's concrete class does not match the declared engine_type, which almost always means engine_type was set independently of the options class.","triggerScenarios":"Calling the factory with options.engine_type == ImageClassificationEngineType.TRANSFORMERS but options is not a TransformersImageClassificationEngineOptions (e.g. an ONNX options object with engine_type reassigned, or a plain/base options object).","commonSituations":"Programmatically switching backends by mutating engine_type on a shared options object; deserializing options from dict/JSON into the wrong class; partial migration when adopting the engine-options refactor.","solutions":["Instantiate TransformersImageClassificationEngineOptions directly instead of mutating another engine's options.","When loading options from configuration, map the engine_type string to the corresponding options class before calling the factory.","Remove any code that assigns engine_type on an existing options instance."],"exampleFix":"# before\noptions = OnnxRuntimeImageClassificationEngineOptions()\noptions.engine_type = ImageClassificationEngineType.TRANSFORMERS\n\n# after\nfrom docling.datamodel.image_classification_engine_options import TransformersImageClassificationEngineOptions\noptions = TransformersImageClassificationEngineOptions()","handlingStrategy":"type-guard","validationCode":"from docling.datamodel.image_classification_engine_options import TransformersImageClassificationEngineOptions\n\nif not isinstance(options, TransformersImageClassificationEngineOptions):\n    options = TransformersImageClassificationEngineOptions(**options.model_dump())","typeGuard":"def is_transformers_options(options) -> TypeGuard[TransformersImageClassificationEngineOptions]:\n    return isinstance(options, TransformersImageClassificationEngineOptions)","tryCatchPattern":"try:\n    engine = create_engine(options=options, ...)\nexcept ValueError as e:\n    if \"Expected TransformersImageClassificationEngineOptions\" in str(e):\n        options = TransformersImageClassificationEngineOptions()\n        engine = create_engine(options=options, ...)\n    else:\n        raise","preventionTips":["Map each engine type to its options class in one lookup used by all config loading.","Reject configs that specify engine_type separately from the options class.","Add unit tests asserting factory + options class pairings."],"tags":["factory","options-mismatch","configuration","transformers"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}