apache/beam · error · ValueError

Unknown transform type %r at

Error message

Unknown transform type %r at %s

What it means

After verifying `type` exists, create_ptransform looks it up in the registry of known providers (`self.providers`). A type that is registered nowhere — neither built-in nor from any configured provider — raises this ValueError, including the spec location for debugging.

Solutions

  1. Fix the typo in the `type:` value (compare against the catalog of built-in YAML transforms).
  2. Upgrade apache_beam (pip install -U apache-beam[yaml]) if the transform exists in a newer release.
  3. Register the custom transform's provider in the pipeline spec / providers configuration.
  4. Check the installed Beam version's docs for exact supported type names.

Example fix

# before
- type: ReadFormBigQuery
# after
- type: ReadFromBigQuery
Defensive patterns

Strategy: validation

Validate before calling

known = set(registered_transform_types)  # built-ins + your providers
for t in pipeline['transforms']:
    if t.get('type') not in known:
        raise ValueError(f'Unknown type {t["type"]} at {t.get("name")}')

Type guard

def is_registered_type(t, providers):
    return isinstance(t, dict) and t.get('type') in providers

Try / catch

try:
    run_pipeline(spec)
except ValueError as e:
    if 'Unknown transform type' in str(e):
        raise UserPipelineError('Fix type name or register a provider; upgrade Beam if newer') from e

Prevention

When it happens

Trigger: A `type:` value matching no registered transform: misspelled built-in names, custom transforms whose provider was never registered, or a transform only present in a newer Beam version than the installed one.

Common situations: Typos like `ReadFormBigQuery`; using a transform added in a later apache-beam release; forgetting to register a custom provider; specs copied from docs for a different Beam version.

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

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

Appendix: source

Thrown at sdks/python/apache_beam/yaml/yaml_transform.py:372

              self.root,
              pcolls,
              spec['transforms'],
              self.providers,
              self.input_providers)
          inner_scope.compute_all()
          if '__implicit_outputs__' in spec['output']:
            return inner_scope.get_outputs(
                spec['output']['__implicit_outputs__'])
          else:
            return {
                key: inner_scope.get_pcollection(value)
                for (key, value) in spec['output'].items()
            }

      return maybe_with_resource_hints(_CompositeTransformStub())

    if spec['type'] not in self.providers:
      raise ValueError(
          'Unknown transform type %r at %s' %
          (spec['type'], identify_object(spec)))

    # TODO(yaml): Perhaps we can do better than a greedy choice here.
    # TODO(yaml): Figure out why this is needed.
    providers_by_input = {k: v for k, v in self.input_providers.items()}
    input_providers = [
        providers_by_input[pcoll] for pcoll in input_pcolls
        if pcoll in providers_by_input
    ]
    provider = self.best_provider(spec, input_providers)
    extra_dependencies, spec = extract_extra_dependencies(spec)
    if extra_dependencies:
      provider = provider.with_extra_dependencies(frozenset(extra_dependencies))

    config = SafeLineLoader.strip_metadata(spec.get('config', {}))
    if not isinstance(config, dict):
      raise ValueError(

View on GitHub (pinned to 12126d8942)