apache/beam · error · ValueError

Missing parameters in model_handler

Error message

Missing parameters in model_handler: {missing_params}

What it means

The YAML run_inference wrapper found the model_handler spec missing required keys (only 'type' and 'config' are expected); the missing key names are interpolated so the user knows exactly what to add to the YAML.

Solutions

Add the missing 'type' key naming the handler
Add the missing 'config' key (use an empty dict {} if all defaults suffice)
Verify YAML indentation nests both keys under model_handler

Example fix

# before
model_handler:
  type: VertexAI
# after
model_handler:
  type: VertexAI
  config:
    endpoint_id: '123'
    project: 'my-project'

Defensive patterns

Strategy: validation

Validate before calling

def check_handler_required(handler):
    missing = {'type', 'config'} - set(handler)
    if missing:
        raise ValueError(f'model_handler missing: {missing}')

Type guard

def is_complete_handler_spec(h):
    return isinstance(h, dict) and {'type', 'config'} <= set(h)

Prevention

Always include both 'type' and 'config' (even empty {})
Validate spec dicts before constructing transforms
Check YAML nesting so keys are not dropped

When it happens

Trigger: model_handler dict given with only 'type' but no 'config', or only 'config' but no 'type', e.g. {'type': 'VertexAI'} without config.

Common situations: Omitting the config block when all defaults apply; forgetting the type key when only options are supplied; YAML nodes dropped due to bad indentation; programmatic dict built conditionally.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

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

Appendix: source

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

      see which args are allowed.

  """

  options.YamlOptions.check_enabled(pcoll.pipeline, 'ML')

  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(

View on GitHub (pinned to 12126d8942)