apache/beam · error · ValueError

must specify either "expression", "callable", or both…

Error message

{transform_name} must specify either "expression", "callable", or both "path" and "name"

What it means

_check_mapping_arguments validates the options of a mapping-style transform (e.g. MapToFields). This ValueError fires when none of the recognized options — expression, callable, path+name — are provided, so there is no way to construct the mapping function.

Solutions

1. Add an `expression` (e.g. "col + 1") to the transform configuration.
2. Or provide a `callable` name or inline callable spec.
3. Or provide both `path` and `name` to load an external callable.
4. Check spelling of configuration keys (expression/callable/path/name).

Example fix

# before
- type: MapToFields
  config: {}
# after
- type: MapToFields
  config:
    language: python
    expression: "col * 2"

assert any([expression, callable, path and name]), 'one of expression/callable/path+name required'

When it happens

Trigger: Calling a mapping transform (via _as_callable) with an empty or all-empty configuration: no expression, no callable, no path and no name.

Common situations: YAML spec with an empty configuration block; copying a transform template and forgetting to fill in the expression; misspelling the option names so all appear unset.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• cannot specify "name" without "path
• cannot specify "path" without "name
• Ambiguous expression type (perhaps missing quoting?)
• Ambiguous expression type (perhaps missing quoting?)
• Can only use expressions on a schema'd input.

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

Appendix: source

Thrown at sdks/python/apache_beam/yaml/yaml_mapping.py:167

    ]
  except (TypeError, ValueError):
    input_fields = []

  if base_type == 'MapToFields':
    for field, value in list(config.get('fields', {}).items()):
      validate_generic_expression(value, input_fields, True, field)

  elif base_type in _str_expression_fields:
    param = _str_expression_fields[base_type]
    validate_generic_expression(
        config.get(param), input_fields, base_type == 'Filter', param)


def _check_mapping_arguments(
    transform_name, expression=None, callable=None, name=None, path=None):
  # Argument checking
  if not expression and not callable and not path and not name:
    raise ValueError(
        f'{transform_name} must specify either "expression", "callable", '
        f'or both "path" and "name"')
  if expression and callable:
    raise ValueError(
        f'{transform_name} cannot specify both "expression" and "callable"')
  if (expression or callable) and (path or name):
    raise ValueError(
        f'{transform_name} cannot specify "expression" or "callable" with '
        f'"path" or "name"')
  if path and not name:
    raise ValueError(f'{transform_name} cannot specify "path" without "name"')
  if name and not path:
    raise ValueError(f'{transform_name} cannot specify "name" without "path"')


_THREAD_LOCAL_JS_CACHE = threading.local()

View on GitHub (pinned to 12126d8942)