apache/beam · error · NotImplementedError

Unknown model handler type: {typ}.

Error message

Unknown model handler type: {typ}.

What it means

The 'type' string in the model_handler dict is looked up in ModelHandlerProvider.handler_types; if it doesn't match a registered handler, run_inference raises this NotImplementedError naming the unknown type.

Source

Thrown at sdks/python/apache_beam/yaml/yaml_ml.py:566

  if not isinstance(model_handler, dict):
    raise ValueError(
        'Invalid model_handler specification. Expected dict but was '
        f'{type(model_handler)}.')
  expected_model_handler_params = {'type', 'config'}
  given_model_handler_params = set(
      SafeLineLoader.strip_metadata(model_handler).keys())
  extra_params = given_model_handler_params - expected_model_handler_params
  if extra_params:
    raise ValueError(f'Unexpected parameters in model_handler: {extra_params}')
  missing_params = expected_model_handler_params - given_model_handler_params
  if missing_params:
    raise ValueError(f'Missing parameters in model_handler: {missing_params}')
  typ = model_handler['type']
  model_handler_provider_type = ModelHandlerProvider.handler_types.get(
      typ, None)
  if not model_handler_provider_type:
    raise NotImplementedError(f'Unknown model handler type: {typ}.')

  model_handler_provider = ModelHandlerProvider.create_handler(model_handler)
  model_handler_provider.validate(model_handler['config'])
  schema = RowTypeConstraint.from_fields(
      named_fields_from_element_type(pcoll.element_type) +
      [(str(inference_tag), model_handler_provider.inference_output_type())])

  return (
      pcoll | RunInference(
          model_handler=KeyedModelHandler(
              model_handler_provider.underlying_handler()).with_preprocess_fn(
                  model_handler_provider._preprocess_fn_internal()).
          with_postprocess_fn(
              model_handler_provider._postprocess_fn_internal()),
          inference_args=inference_args)
      | beam.Map(
          lambda row: beam.Row(
              **{

View on GitHub (pinned to 12126d8942)

Solutions

1. Use a registered type string, e.g. 'VertexAI' or 'HuggingFacePipeline' (check ModelHandlerProvider.handler_types for exact keys)
2. Upgrade apache_beam if the handler type exists only in newer releases
3. Register custom handlers via ModelHandlerProvider before calling run_inference
4. Fix casing/typos in the type value

Example fix

# before
model_handler:
  type: vertex_ai
  config: {...}
# after
model_handler:
  type: VertexAI
  config: {...}

from apache_beam.yaml.yaml_ml import ModelHandlerProvider
def check_handler_type(typ):
    if typ not in ModelHandlerProvider.handler_types:
        raise ValueError(f'Unknown handler type {typ!r}; known: {sorted(ModelHandlerProvider.handler_types)}')

def is_known_handler_type(typ):
    from apache_beam.yaml.yaml_ml import ModelHandlerProvider
    return typ in ModelHandlerProvider.handler_types

try:
    RunInference(model_handler=spec)
except NotImplementedError as e:
    if 'Unknown model handler type' in str(e):
        log_known_types(); correct_spec()
    else:
        raise

When it happens

Trigger: model_handler['type'] is a misspelled or unsupported value, e.g. 'VertexAIModelHandlerJSON', 'huggingface' with wrong casing, or a handler not registered in the installed Beam version.

Common situations: Typos or wrong casing in YAML; using a handler type from a newer Beam version than installed; using internal class names instead of the registered YAML type strings; custom handlers not registered via ModelHandlerProvider.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• Invalid model_handler specification. Expected dict but was {
• Unexpected parameters in model_handler: {extra_params}
• Missing parameters in model_handler: {missing_params}
• Missing type in ML transform spec {spec}
• Missing config in ML transform spec {spec}

AI-assisted analysis of apache/beam@12126d8942 (2026-09-13). Data as JSON: /api/errors/78ff010aad7ff9dc. Report an issue: GitHub.