apache/beam · error · ValueError

Unknown ML transform type: %r

Error message

Unknown ML transform type: %r

What it means

After resolving the 'type' key in an ML transform spec, _config_to_obj found no registered provider under that name; it is a generic unknown-type guard for the provider registry used by YAML ML transforms.

Source

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

                  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(
              **{
                  **row[0]._asdict(), str(inference_tag): row[1]
              })).with_output_types(schema))


def _config_to_obj(spec):
  if 'type' not in spec:
    raise ValueError(f"Missing type in ML transform spec {spec}")
  if 'config' not in spec:
    raise ValueError(f"Missing config in ML transform spec {spec}")
  constructor = _transform_constructors.get(spec['type'])
  if constructor is None:
    raise ValueError("Unknown ML transform type: %r" % spec['type'])
  return constructor(**spec['config'])


@beam.ptransform.ptransform_fn
def ml_transform(
    pcoll,
    write_artifact_location: Optional[str] = None,
    read_artifact_location: Optional[str] = None,
    transforms: Optional[list[Any]] = None):
  if MLTransform is None:
    raise ValueError(
        'No MLTransform found. Please install tensorflow-transform or '
        'sentence-transformers to use this transform.')
  options.YamlOptions.check_enabled(pcoll.pipeline, 'ML')
  result_ml_transform = MLTransform(
      write_artifact_location=write_artifact_location,
      read_artifact_location=read_artifact_location,
      transforms=[_config_to_obj(t) for t in transforms] if transforms else [])

View on GitHub (pinned to 12126d8942)

Solutions

1. Use a supported type such as 'RunInference'
2. Check _transform_constructors keys for the exact accepted names
3. Upgrade apache_beam if the transform exists only in newer versions
4. Register custom constructors in _transform_constructors before use

Example fix

# before
type: MLInference
# after
type: RunInference

from apache_beam.yaml.yaml_ml import _transform_constructors
def check_transform_type(typ):
    if typ not in _transform_constructors:
        raise ValueError(f'Unknown ML transform {typ!r}; known: {sorted(_transform_constructors)}')

def is_known_transform_type(typ):
    from apache_beam.yaml.yaml_ml import _transform_constructors
    return typ in _transform_constructors

try:
    t = _config_to_obj(spec)
except ValueError as e:
    if 'Unknown ML transform type' in str(e):
        log_known_types(); correct_spec()
    else:
        raise

When it happens

Trigger: spec['type'] not in _transform_constructors, e.g. type: Inference instead of RunInference, wrong casing ('runinference'), or a transform added in a newer Beam version than installed.

Common situations: Typos in YAML transform type names; using aliases not supported by this Beam version; custom transforms not registered in _transform_constructors; docs from a different release.

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

• Unknown enrichment source: {enrichment_handler}
• Unknown format: {format}
• Invalid model_handler specification. Expected dict but was {
• Unexpected parameters in model_handler: {extra_params}
• Missing parameters in model_handler: {missing_params}

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