apache/beam · error · ValueError

"RenamingProvider mappings must be dict of transform…

Error message

"RenamingProvider mappings must be dict of transform mappings."

What it means

Raised by RenamingProvider.expand_mappings when the mappings argument is not a dict. RenamingProvider requires mappings to be a dict of transform-name -> mapping (target transform name or config mapping dict).

Solutions

1. Pass mappings as a dict, e.g. {'MyRead': 'Read'} or {'MyRead': {'underlying': 'Read', 'config': {...}}}.
2. Fix the YAML provider spec so mappings is a map (key: value pairs), not a list.
3. Check for None: provide a default empty dict if no mappings are needed (with a corresponding transforms list).

Example fix

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

def validate_mappings_shape(mappings):
    if not isinstance(mappings, dict):
        raise TypeError('mappings must be a dict of transform mappings')

def is_valid_mappings(mappings):
    return isinstance(mappings, dict)

try:
    provider = RenamingProvider(base, transforms, mappings)
except ValueError as e:
    if 'must be dict' in str(e):
        logging.error('Fix mappings shape to a dict: %s', e)
        raise
    raise

When it happens

Trigger: Passing mappings as a list, string, or None to RenamingProvider, e.g. mappings=['Read'] or a YAML mapping that parsed as a scalar.

Common situations: Malformed YAML provider spec where the mappings section is a sequence rather than a map, or programmatic construction with the wrong shape.

Related errors

• 'elements must be a list of elements'
• Invalid model_handler specification. Expected dict but was
• Returned output name
• Transform returned an unexpected type
• 'Transform mapping must be a dict.'

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

Appendix: source

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

      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

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

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

View on GitHub (pinned to 12126d8942)