{"record":{"id":"290e5d2a3a116e60","repo":"docling-project/docling","slug":"expected-transformersobjectdetectionengineoptions","errorCode":null,"errorMessage":"Expected TransformersObjectDetectionEngineOptions, got {type(options)}","messagePattern":"Expected TransformersObjectDetectionEngineOptions, got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"docling/models/inference_engines/object_detection/factory.py","lineNumber":78,"sourceCode":"            )\n\n        return OnnxRuntimeObjectDetectionEngine(\n            options=options,\n            model_config=model_config,\n            artifacts_path=artifacts_path,\n            accelerator_options=accelerator_options,\n        )\n\n    elif options.engine_type == ObjectDetectionEngineType.TRANSFORMERS:\n        from docling.datamodel.object_detection_engine_options import (\n            TransformersObjectDetectionEngineOptions,\n        )\n        from docling.models.inference_engines.object_detection.transformers_engine import (\n            TransformersObjectDetectionEngine,\n        )\n\n        if not isinstance(options, TransformersObjectDetectionEngineOptions):\n            raise ValueError(\n                f\"Expected TransformersObjectDetectionEngineOptions, got {type(options)}\"\n            )\n\n        return TransformersObjectDetectionEngine(\n            options=options,\n            model_config=model_config,\n            accelerator_options=accelerator_options,\n            artifacts_path=artifacts_path,\n        )\n\n    elif options.engine_type == ObjectDetectionEngineType.API_KSERVE_V2:\n        from docling.datamodel.object_detection_engine_options import (\n            ApiKserveV2ObjectDetectionEngineOptions,\n        )\n        from docling.models.inference_engines.object_detection.api_kserve_v2_engine import (\n            ApiKserveV2ObjectDetectionEngine,\n        )\n","sourceCodeStart":60,"sourceCodeEnd":96,"githubUrl":"https://github.com/docling-project/docling/blob/61d76f1ff3f8428065465889f7b4577da7df704c/docling/models/inference_engines/object_detection/factory.py#L60-L96","documentation":"The factory raises ValueError when options.engine_type is TRANSFORMERS but the options object is not a TransformersObjectDetectionEngineOptions instance. Each engine_type branch validates the concrete options type so that downstream engines receive the fields they expect.","triggerScenarios":"Setting engine_type = ObjectDetectionEngineType.TRANSFORMERS on a non-Transformers options object (ONNX or KServe options class) and invoking the factory.","commonSituations":"Switching engines by flipping only the engine_type enum in an existing config; YAML-driven pipelines where the options class mapping is out of sync with the enum; refactors that changed option class names.","solutions":["Construct TransformersObjectDetectionEngineOptions directly — it carries the correct engine_type by default.","When changing engine families in a config, replace the whole options object, not just the engine_type field.","Add a startup assertion that type(options) matches the expected class per engine_type."],"exampleFix":"# before\nopts = OnnxRuntimeObjectDetectionEngineOptions()\nopts.engine_type = ObjectDetectionEngineType.TRANSFORMERS\n\n# after\nfrom docling.datamodel.object_detection_engine_options import TransformersObjectDetectionEngineOptions\nopts = TransformersObjectDetectionEngineOptions()","handlingStrategy":"type-guard","validationCode":"from docling.datamodel.object_detection_engine_options import TransformersObjectDetectionEngineOptions\nassert isinstance(opts, TransformersObjectDetectionEngineOptions), type(opts)","typeGuard":"def is_transformers_opts(o: object) -> TypeGuard[TransformersObjectDetectionEngineOptions]:\n    return isinstance(o, TransformersObjectDetectionEngineOptions)","tryCatchPattern":"try:\n    engine = create_object_detection_engine(options=opts)\nexcept ValueError as e:\n    raise ConfigurationError(str(e)) from e","preventionTips":["Replace the whole options object when switching engine families.","Add startup isinstance checks for deserialized options.","Write configs per-engine instead of mutating a shared template."],"tags":["configuration","factory","type-mismatch","object-detection"],"backgroundTag":null,"analyzedSha":"61d76f1ff3f8428065465889f7b4577da7df704c","analyzedAt":"2026-08-14T23:53:18.727Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}