{"record":{"id":"200bf64cc8b6231f","repo":"apache/beam","slug":"invalid-model-handler-specification","errorCode":null,"errorMessage":"Invalid model_handler specification.","messagePattern":"Invalid model_handler specification\\.","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/yaml/yaml_ml.py","lineNumber":108,"sourceCode":"      if callable and (path or name):\n        raise ValueError(\n            f\"Cannot specify 'callable' with 'path' and 'name' for {typ} \"\n            f\"function.\")\n      if path and name:\n        return python_callable.PythonCallableWithSource.load_from_script(\n            FileSystems.open(path).read().decode(), name)\n      elif callable:\n        return python_callable.PythonCallableWithSource(callable)\n      else:\n        raise ValueError(\n            f\"Must specify one of 'callable' or 'path' and 'name' for {typ} \"\n            f\"function.\")\n\n    if processing_transform:\n      if isinstance(processing_transform, dict):\n        return _parse_config(**processing_transform)\n      else:\n        raise ValueError(\"Invalid model_handler specification.\")\n\n  def underlying_handler(self):\n    return self._handler\n\n  @staticmethod\n  def default_preprocess_fn():\n    raise ValueError(\n        'Model Handler does not implement a default preprocess '\n        'method. Please define a preprocessing method using the '\n        '\\'preprocess\\' tag. This is required in most cases because '\n        'most models will have a different input shape, so the model '\n        'cannot generalize how the input Row should be transformed. For '\n        'an example preprocess method, see VertexAIModelHandlerJSONProvider')\n\n  def _preprocess_fn_internal(self):\n    return lambda row: (row, self._preprocess_fn(row))\n\n  @staticmethod","sourceCodeStart":90,"sourceCodeEnd":126,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/yaml/yaml_ml.py#L90-L126","documentation":"`ModelHandlerProvider.parse_processing_transform` (yaml_ml.py:108) expects the model handler specification to be a dict that names a registered handler type. If the spec is provided but is not a dict, ValueError('Invalid model_handler specification.') is raised.","triggerScenarios":"Passing the model_handler / processing transform spec as a string or other non-dict value, e.g. model_handler: VertexAIModelHandlerJSON instead of model_handler: {type: VertexAIModelHandlerJSON, ...}.","commonSituations":"YAML config where the handler is written as a plain scalar name instead of a mapping with a type key; JSON configs converted incorrectly; copy-paste from docs losing nesting.","solutions":["Wrap the handler spec in a mapping with the appropriate type key, e.g. {type: VertexAIModelHandlerJSON, project: ..., endpoint_id: ...}.","Check that the YAML indentation keeps model_handler as a nested dict, not a scalar.","Verify the handler type string is registered via ModelHandlerProvider.register_handler_type."],"exampleFix":"# before\nmodel_handler: VertexAIModelHandlerJSON\n# after\nmodel_handler:\n  type: VertexAIModelHandlerJSON\n  project: my-project\n  endpoint_id: 123","handlingStrategy":"validation","validationCode":"spec = cfg.get('model_handler')\nif spec is not None and not isinstance(spec, dict):\n    raise ValueError('model_handler must be a mapping with a type key')","typeGuard":"def is_handler_spec(v):\n    return isinstance(v, dict) and isinstance(v.get('type'), str)","tryCatchPattern":"try:\n    handler = ModelHandlerProvider.parse_processing_transform(spec, typ)\nexcept ValueError as e:\n    raise YamlConfigError('model_handler must be a dict like {type: ...}') from e","preventionTips":["Always write model_handler as a nested mapping with a `type` key.","Check YAML indentation so nested keys don't collapse to scalars.","Validate the whole YAML transform against Beam YAML's schema before running."],"tags":["python","apache-beam","yaml-ml","config-format"],"backgroundTag":"invalid-argument-format","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}