apache/beam · error · ValueError

Unexpected parameters in model_handler: {extra_params}

Error message

Unexpected parameters in model_handler: {extra_params}

What it means

After confirming model_handler is a dict, run_inference allows only the keys 'type' and 'config'. Any additional keys are collected into extra_params and reported in this ValueError listing the offending names.

Source

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

      'inference'.
    inference_args: Extra arguments for models whose inference call requires
      extra parameters. Make sure to check the underlying ModelHandler docs to
      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(

View on GitHub (pinned to 12126d8942)

Solutions

1. Move all handler options under the 'config' key
2. Keep only 'type' and 'config' at the model_handler level
3. Re-check YAML indentation so endpoint_id/project etc. are nested under config

Example fix

# before
model_handler:
  type: VertexAI
  endpoint_id: '123'
# after
model_handler:
  type: VertexAI
  config:
    endpoint_id: '123'

def check_handler_keys(handler):
    extra = set(handler) - {'type', 'config'}
    if extra:
        raise ValueError(f'Move to config: {extra}')

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

When it happens

Trigger: model_handler dict containing keys besides 'type' and 'config', e.g. {'type': 'VertexAI', 'endpoint_id': ..., 'project': ...} where handler options were placed at the top level instead of inside 'config'.

Common situations: Flattening handler options next to type in YAML; renaming config to something else; copying older YAML examples; JSON configs merging handler and endpoint settings.

Related errors

• Missing parameters in model_handler: {missing_params}
• Missing type in ML transform spec {spec}
• Missing config in ML transform spec {spec}
• Node ID cannot be empty
• Edge source and target cannot be empty

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