{"record":{"id":"4481bf4e57b4f37f","repo":"apache/beam","slug":"invalid-model-handler-specification-expected-dict-but-was","errorCode":null,"errorMessage":"Invalid model_handler specification. Expected dict but was {type(model_handler)}.","messagePattern":"Invalid model_handler specification\\. Expected dict but was (.+?)\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/yaml/yaml_ml.py","lineNumber":550,"sourceCode":"  Args:\n    model_handler: Specifies the parameters for the respective\n          model_handler in a YAML/JSON format. To see the full set of\n          handler_config parameters, see their corresponding doc pages:\n\n            - [VertexAIModelHandlerJSON](https://beam.apache.org/releases/pydoc/current/apache_beam.yaml.yaml_ml.VertexAIModelHandlerJSONProvider) # pylint: disable=line-too-long\n            - [HuggingFacePipelineModelHandler](https://beam.apache.org/releases/pydoc/current/apache_beam.yaml.yaml_ml.HuggingFacePipelineModelHandlerProvider) # pylint: disable=line-too-long\n    inference_tag: The tag to use for the returned inference. Default is\n      'inference'.\n    inference_args: Extra arguments for models whose inference call requires\n      extra parameters. Make sure to check the underlying ModelHandler docs to\n      see which args are allowed.\n\n  \"\"\"\n\n  options.YamlOptions.check_enabled(pcoll.pipeline, 'ML')\n\n  if not isinstance(model_handler, dict):\n    raise ValueError(\n        'Invalid model_handler specification. Expected dict but was '\n        f'{type(model_handler)}.')\n  expected_model_handler_params = {'type', 'config'}\n  given_model_handler_params = set(\n      SafeLineLoader.strip_metadata(model_handler).keys())\n  extra_params = given_model_handler_params - expected_model_handler_params\n  if extra_params:\n    raise ValueError(f'Unexpected parameters in model_handler: {extra_params}')\n  missing_params = expected_model_handler_params - given_model_handler_params\n  if missing_params:\n    raise ValueError(f'Missing parameters in model_handler: {missing_params}')\n  typ = model_handler['type']\n  model_handler_provider_type = ModelHandlerProvider.handler_types.get(\n      typ, None)\n  if not model_handler_provider_type:\n    raise NotImplementedError(f'Unknown model handler type: {typ}.')\n\n  model_handler_provider = ModelHandlerProvider.create_handler(model_handler)","sourceCodeStart":532,"sourceCodeEnd":568,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/yaml/yaml_ml.py#L532-L568","documentation":"run_inference expects the model_handler argument to be a dict of the form {type: ..., config: ...}. Passing any other type (string, object, list, None) triggers this ValueError which reports the received Python type.","triggerScenarios":"Passing a preconstructed ModelHandler object or a string name instead of a YAML-style dict into RunInference's model_handler; YAML parse producing a non-mapping node; programmatic use of ml_transform with a handler instance.","commonSituations":"Reusing code written for apache_beam.ml.inference direct APIs with the YAML transform; YAML unquoted scalars like `model_handler: VertexAI` parsed as a string; JSON configs where handler was flattened.","solutions":["Pass a dict: {'type': <handler type>, 'config': {...}}","If you have a handler object, construct it via the YAML provider instead of passing the instance","Quote/structure the YAML so model_handler is a mapping","Convert JSON config so model_handler is an object with type and config keys"],"exampleFix":"# before\nRunInference(model_handler='VertexAI')\n# after\nRunInference(model_handler={'type': 'VertexAI', 'config': {'endpoint_id': '123', 'project': 'my-project'}})","handlingStrategy":"type-guard","validationCode":"def check_model_handler(handler):\n    if not isinstance(handler, dict):\n        raise TypeError(f'model_handler must be a dict, got {type(handler).__name__}')","typeGuard":"def is_valid_handler_spec(h):\n    return isinstance(h, dict) and 'type' in h and 'config' in h","tryCatchPattern":"try:\n    RunInference(model_handler=spec)\nexcept ValueError as e:\n    if 'Expected dict' in str(e):\n        spec = {'type': 'VertexAI', 'config': spec}\n        RunInference(model_handler=spec)\n    else:\n        raise","preventionTips":["Always pass model_handler as {type, config} dict","Do not pass preconstructed ModelHandler objects to YAML transforms","Validate pipeline YAML against the schema before running"],"tags":["python","apache-beam","yaml","type-mismatch","ml"],"backgroundTag":"type-mismatch","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}