apache/beam · error · ValueError

Invalid model_handler specification. Expected dict but was {

Error message

Invalid model_handler specification. Expected dict but was {type(model_handler)}.

What it means

run_inference expects the model_handler argument to be a dict of the form {type: ..., config: ...}. Passing any other type (string, object, list, None) triggers this ValueError which reports the received Python type.

Source

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

  Args:
    model_handler: Specifies the parameters for the respective
          model_handler in a YAML/JSON format. To see the full set of
          handler_config parameters, see their corresponding doc pages:

            - [VertexAIModelHandlerJSON](https://beam.apache.org/releases/pydoc/current/apache_beam.yaml.yaml_ml.VertexAIModelHandlerJSONProvider) # pylint: disable=line-too-long
            - [HuggingFacePipelineModelHandler](https://beam.apache.org/releases/pydoc/current/apache_beam.yaml.yaml_ml.HuggingFacePipelineModelHandlerProvider) # pylint: disable=line-too-long
    inference_tag: The tag to use for the returned inference. Default is
      '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)

View on GitHub (pinned to 12126d8942)

Solutions

Pass a dict: {'type': <handler type>, 'config': {...}}
If you have a handler object, construct it via the YAML provider instead of passing the instance
Quote/structure the YAML so model_handler is a mapping
Convert JSON config so model_handler is an object with type and config keys

Example fix

# before
RunInference(model_handler='VertexAI')
# after
RunInference(model_handler={'type': 'VertexAI', 'config': {'endpoint_id': '123', 'project': 'my-project'}})

Defensive patterns

Strategy: type-guard

Validate before calling

def check_model_handler(handler):
    if not isinstance(handler, dict):
        raise TypeError(f'model_handler must be a dict, got {type(handler).__name__}')

Type guard

def is_valid_handler_spec(h):
    return isinstance(h, dict) and 'type' in h and 'config' in h

Try / catch

try:
    RunInference(model_handler=spec)
except ValueError as e:
    if 'Expected dict' in str(e):
        spec = {'type': 'VertexAI', 'config': spec}
        RunInference(model_handler=spec)
    else:
        raise

Prevention

Always pass model_handler as {type, config} dict
Do not pass preconstructed ModelHandler objects to YAML transforms
Validate pipeline YAML against the schema before running

When it happens

Trigger: Passing a preconstructed ModelHandler object or a string name instead of a YAML-style dict into RunInference's model_handler; YAML parse producing a non-mapping node; programmatic use of ml_transform with a handler instance.

Common situations: Reusing code written for apache_beam.ml.inference direct APIs with the YAML transform; YAML unquoted scalars like `model_handler: VertexAI` parsed as a string; JSON configs where handler was flattened.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

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