What causes "'Transform mapping must be a dict.'" in apache/beam?

Convert the transforms argument to a plain dict: dict(transforms).

apache/beam · error · ValueError

'Transform mapping must be a dict.'

Error message

'Transform mapping must be a dict.'

What it means

YamlProvider.__init__ (yaml_provider.py:479) requires its 'transforms' argument to be a dict mapping transform names to configurations. Passing any other Mapping/list raises ValueError 'Transform mapping must be a dict.'

Source

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

  def _affinity(self, other: "Provider"):
    if isinstance(other, InlineProvider):
      return 50
    else:
      return super()._affinity(other)

  def _with_extra_dependencies(self, dependencies: Iterable[str]):
    return ExternalPythonProvider(
        self._urns, None, set(self._packages).union(set(dependencies)))


@ExternalProvider.register_provider_type('yaml')
class YamlProvider(Provider):
  def __init__(
      self,
      transforms: Mapping[str, Mapping[str, Any]],
      provider_base_path: Optional[str] = None):
    if not isinstance(transforms, dict):
      raise ValueError('Transform mapping must be a dict.')
    self._transforms = transforms
    self._provider_base_path = provider_base_path

  def available(self):
    return True

  def cache_artifacts(self):
    pass

  def provided_transforms(self):
    return self._transforms.keys()

  def config_schema(self, type):
    return json_utils.json_schema_to_beam_schema(self.json_config_schema(type))

  def json_config_schema(self, type):
    return dict(
        type='object',

View on GitHub (pinned to 12126d8942)

Solutions

Convert the transforms argument to a plain dict: dict(transforms).
Fix the provider spec so 'transforms' is a YAML mapping (name: config), not a list of entries.
If using a custom Mapping type, wrap or copy it into a dict before constructing YamlProvider.

Example fix

// before
YamlProvider(transforms=[{'A': {...}}])
// after
YamlProvider(transforms={'A': {...}})

Defensive patterns

Strategy: type-guard

Validate before calling

if not isinstance(transforms, dict):
    transforms = dict(transforms)  # or fix the source spec to be a mapping

Type guard

def is_transform_mapping(x) -> bool:
    return isinstance(x, dict) and all(isinstance(k, str) for k in x)

Try / catch

try:
    p = YamlProvider(transforms)
except ValueError as e:
    log.error('YamlProvider needs a dict of transforms: %s', e)
    raise

Prevention

Author 'transforms' in YAML as a mapping, never a list of entries.
Copy non-dict Mappings into plain dict before constructing YamlProvider.
Add a schema check for provider specs that asserts transforms is a mapping.

When it happens

Trigger: Constructing YamlProvider(transforms=...) programmatically with a list, OrderedDict-like non-dict mapping, or a JSON array; a provider spec whose 'transforms' value parses as a list rather than a mapping.

Common situations: Building providers from JSON/YAML where 'transforms' was authored as a sequence; passing a collections.abc.Mapping that isn't a dict subclass (the check is isinstance(transforms, dict)).

Related errors

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