apache/beam · error · ValueError

"RenamingProvider transform mappings must be dict or…

Error message

"RenamingProvider transform mappings must be dict or specify transform that has mappings within same provider."

What it means

Raised by RenamingProvider.expand_mappings when a mappings value is a string alias but that alias does not itself exist as a key in the same mappings dict. String values must reference another transform's mappings within the same provider.

Solutions

Give the target transform its own mapping entry: mappings={'MyRead': 'Read', 'Read': {...actual mapping...}}.
Replace the string alias with the actual mapping dict: mappings={'MyRead': {'input': ..., 'output': ...}}.
Fix the alias spelling so it matches an existing key in mappings.

Example fix

// before
mappings={'MyRead': 'Read'}
// after
mappings={'MyRead': 'Read', 'Read': {'config_mapping': {...}}}

Defensive patterns

Strategy: validation

Validate before calling

def validate_string_aliases(mappings):
    for k, v in mappings.items():
        if isinstance(v, str) and v not in mappings:
            raise ValueError(f'Alias {v!r} for {k!r} must be another key in mappings')

Try / catch

try:
    provider = RenamingProvider(base, transforms, mappings)
except ValueError as e:
    if 'must be dict or specify transform' in str(e):
        logging.error('String alias target missing from mappings: %s', e)
        raise
    raise

Prevention

Remember string values are aliases to other mappings keys, not underlying transform names.
Prefer inline dict mappings over string aliases to avoid indirection bugs.
Add a pre-load validation pass resolving aliases before constructing the provider.

When it happens

Trigger: mappings={'MyRead': 'Read'} where 'Read' is not itself a key in mappings — string values must point at another mapping entry, not directly at the underlying transform name that lacks its own mappings.

Common situations: Authors assume string values are direct aliases of underlying transform names, but the provider requires the target name to also have an entry (typically a dict of config mappings) in the same mappings dict.

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

Appendix: source

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

          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

  def available(self) -> bool:
    return self._underlying_provider.available()

  def provided_transforms(self) -> Iterable[str]:
    return self._transforms.keys()

  def config_schema(self, type):
    underlying_schema = self._underlying_provider.config_schema(
        self._transforms[type])
    if underlying_schema is None:
      return None
    defaults = self._defaults.get(type, {})

View on GitHub (pinned to 12126d8942)