{"record":{"id":"b2a18c47db7f53f4","repo":"apache/beam","slug":"unable-to-instantiate-model-handler-of-type-typ-exn","errorCode":null,"errorMessage":"Unable to instantiate model handler of type {typ}. {exn}","messagePattern":"Unable to instantiate model handler of type (.+?)\\. (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"sdks/python/apache_beam/yaml/yaml_ml.py","lineNumber":155,"sourceCode":"  @classmethod\n  def register_handler_type(cls, type_name):\n    def apply(constructor):\n      cls.handler_types[type_name] = constructor\n      return constructor\n\n    return apply\n\n  @classmethod\n  def create_handler(cls, model_handler_spec) -> \"ModelHandlerProvider\":\n    typ = model_handler_spec['type']\n    config = model_handler_spec['config']\n    try:\n      result = cls.handler_types[typ](**config)\n      if not hasattr(result, 'to_json'):\n        result.to_json = lambda: model_handler_spec\n      return result\n    except Exception as exn:\n      raise ValueError(\n          f'Unable to instantiate model handler of type {typ}. {exn}')\n\n\n@ModelHandlerProvider.register_handler_type('VertexAIModelHandlerJSON')\nclass VertexAIModelHandlerJSONProvider(ModelHandlerProvider):\n  def __init__(\n      self,\n      endpoint_id: str,\n      project: str,\n      location: str,\n      preprocess: dict[str, str],\n      postprocess: Optional[dict[str, str]] = None,\n      experiment: Optional[str] = None,\n      network: Optional[str] = None,\n      private: bool = False,\n      invoke_route: Optional[str] = None,\n      min_batch_size: Optional[int] = None,\n      max_batch_size: Optional[int] = None,","sourceCodeStart":137,"sourceCodeEnd":173,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/python/apache_beam/yaml/yaml_ml.py#L137-L173","documentation":"`ModelHandlerProvider.create_handler` (yaml_ml.py:155) looks up the registered provider for the requested handler type and constructs it with the given config. Any exception during construction (bad kwargs, missing credentials, wrong types, unregistered type raising KeyError) is re-raised as ValueError('Unable to instantiate model handler of type {typ}. {exn}') chaining the original error.","triggerScenarios":"Calling create_handler with a type whose provider constructor raises: wrong/missing config keys, invalid credentials, malformed JSON specs, or a type string not in handler_types (KeyError wrapped).","commonSituations":"Misspelled handler type names; Vertex AI config missing project/endpoint_id; GCS model paths without credentials; version drift where a config parameter was renamed.","solutions":["Read the chained {exn} message to identify the underlying constructor failure and fix the config accordingly.","Verify the handler type is registered and spelled exactly (e.g. 'VertexAIModelHandlerJSON').","Check required constructor parameters (project, endpoint_id, model_path) and credentials are present/valid.","Test handler construction directly in Python to get a clearer stack trace before running the pipeline."],"exampleFix":"# before\nmodel_handler:\n  type: VertexAIModelHandlerJSON\n  endpoint_id: '123'\n# after\nmodel_handler:\n  type: VertexAIModelHandlerJSON\n  project: my-gcp-project\n  endpoint_id: '123'\n  location: us-central1","handlingStrategy":"try-catch","validationCode":"assert isinstance(spec, dict) and spec.get('type') in ModelHandlerProvider.handler_types, f\"unknown handler type {spec.get('type') if isinstance(spec, dict) else spec}\"","typeGuard":"def is_registered_handler(spec):\n    return isinstance(spec, dict) and spec.get('type') in ModelHandlerProvider.handler_types","tryCatchPattern":"try:\n    handler = ModelHandlerProvider.create_handler(spec)\nexcept ValueError as e:\n    log.error('handler construction failed: %s', e)\n    raise ModelConfigError(str(e)) from e","preventionTips":["Verify handler type names against the registered list before configuring.","Confirm required constructor args (project, endpoint_id, model path) and valid credentials.","Construct the handler in a plain Python script first to see the raw underlying exception.","Pin Beam version and check changelogs for renamed handler config parameters."],"tags":["python","apache-beam","yaml-ml","model-handler"],"backgroundTag":"invalid-config-value","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"}