What causes "f'Missing transform {transform} in mappings.'" in apache/beam?

Add a mapping entry for the missing transform, e.g. mappings: {'MyRead': 'ActualRead'}.

apache/beam · error · ValueError

f'Missing transform in mappings.

Error message

f'Missing transform {transform} in mappings.'

What it means

Raised by RenamingProvider's constructor when a transform it is supposed to expose (a key of 'transforms') has no corresponding entry in the provided mappings. Every exposed transform must have a rename/alias mapping to an underlying transform.

Solutions

Add a mapping entry for the missing transform, e.g. mappings: {'MyRead': 'ActualRead'}.
Fix typos so the transform key matches a key in mappings exactly.
Remove the transform from the transforms list if it should not be exposed.

Example fix

# before
RenamingProvider(provider, transforms=['MyRead'], mappings={})
# after
RenamingProvider(provider, transforms=['MyRead'], mappings={'MyRead': 'Read'})

Defensive patterns

Strategy: validation

Validate before calling

def validate_renaming_provider(transforms, mappings):
    missing = [t for t in transforms if t not in mappings]
    if missing:
        raise ValueError(f'Transforms missing from mappings: {missing}')

Try / catch

try:
    provider = RenamingProvider(base, transforms, mappings)
except ValueError as e:
    if 'Missing transform' in str(e):
        logging.error('Add mappings for all exposed transforms: %s', e)
        raise
    raise

Prevention

Keep the transforms and mappings lists in lockstep; derive mappings keys from transforms at build time.
Regenerate mappings when the underlying provider's transform set changes (e.g. Beam upgrades).
Add a unit test that constructs the provider to catch drift early.

When it happens

Trigger: Creating a RenamingProvider where transforms lists a transform name (e.g. 'MyRead') that is absent from the mappings dict, typically after adding a new transform to the underlying provider without updating mappings.

Common situations: Version drift: the underlying provider gained a transform, or a typo in the mappings key means the transform name doesn't match exactly.

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/ba1ccfbdcc00b1f4. Report an issue: GitHub.

Appendix: source

Thrown at sdks/python/apache_beam/yaml/yaml_provider.py:1500


@ExternalProvider.register_provider_type('renaming')
class RenamingProvider(Provider):
  def __init__(
      self,
      transforms,
      provider_base_path,
      mappings,
      underlying_provider,
      defaults=None):
    if isinstance(underlying_provider, dict):
      underlying_provider = ExternalProvider.provider_from_spec(
          provider_base_path, underlying_provider)
    self._transforms = transforms
    self._underlying_provider = underlying_provider
    for transform in transforms.keys():
      if transform not in mappings:
        raise ValueError(f'Missing transform {transform} in mappings.')
    self._mappings = self.expand_mappings(mappings)
    self._defaults = defaults or {}

  @staticmethod
  def expand_mappings(mappings):
    if not isinstance(mappings, dict):
      raise ValueError(
          "RenamingProvider mappings must be dict of transform "
          "mappings.")
    for key, value in mappings.items():
      if isinstance(value, str):
        if value not in mappings.keys():
          raise ValueError(
              "RenamingProvider transform mappings must be dict or "
              "specify transform that has mappings within same "
              "provider.")
        mappings[key] = mappings[value]
    return mappings

View on GitHub (pinned to 12126d8942)