apache/beam · error · TypeError

Side inputs must have defaults for MapTuple.

Error message

Side inputs must have defaults for MapTuple.

What it means

MapTuple spreads the input tuple plus side inputs as positional args to fn. Each side input must correspond to a parameter of fn that has a default value, because the wrapper may be invoked with fewer positional args when side inputs are deferred. If the number of defaulted parameters is smaller than args+kwargs (side inputs), Beam raises TypeError.

Solutions

  1. Give each side-input parameter a default value in fn, e.g. def fn(k, v, extra=None): ...
  2. Reduce the number of side inputs to match the number of defaulted parameters.
  3. Switch to beam.Map / beam.ParDo if you need explicit side-input handling without defaults.
  4. Rename side input usage so positional/keyword side inputs bind to fn's defaulted args (use kwargs for named side inputs).

Example fix

// before
def fn(k, v, scale): ...  # no default
beam.MapTuple(fn, 'scale_label')
// after
def fn(k, v, scale=1.0): ...
beam.MapTuple(fn, 'scale_label')
Defensive patterns

Strategy: validation

Validate before calling

from apache_beam.transforms.ptransform import get_function_args_defaults
arg_names, defaults = get_function_args_defaults(fn)
num_defaults = len(defaults)
assert num_defaults >= len(args) + len(kwargs), 'need a defaulted param per side input for MapTuple'

Type guard

def side_inputs_have_defaults(fn, args, kwargs):
    return len(get_function_args_defaults(fn)[1]) >= len(args) + len(kwargs)

Try / catch

try:
    out = pcoll | beam.MapTuple(fn, *side_labels)
except TypeError as e:
    if 'defaults for MapTuple' in str(e):
        raise ValueError('Add default values to fn params for each side input') from e
    raise

Prevention

When it happens

Trigger: beam.MapTuple(fn, 'side_input_label', other_label) where fn's signature has fewer parameters with defaults than the number of side inputs passed.

Common situations: Adding a side input with pvalue.AsDict/AsIter without extending fn's signature with default-valued parameters; side inputs added by someone else later; converting Map to MapTuple without adjusting the signature.

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

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

Appendix: source

Thrown at sdks/python/apache_beam/transforms/core.py:2204

    A :class:`~apache_beam.pvalue.PCollection` containing the
    :func:`MapTuple` outputs.

  Raises:
    TypeError: If the **fn** passed as argument is not a callable.
      Typical error is to pass a :class:`DoFn` instance which is supported only
      for :class:`ParDo`.
  """
  if not callable(fn):
    raise TypeError(
        'MapTuple can be used only with callable objects. '
        'Received %r instead.' % (fn))

  label = 'MapTuple(%s)' % ptransform.label_from_callable(fn)

  arg_names, defaults = get_function_args_defaults(fn)
  num_defaults = len(defaults)
  if num_defaults < len(args) + len(kwargs):
    raise TypeError('Side inputs must have defaults for MapTuple.')

  if defaults or args or kwargs:
    wrapper = lambda x, *args, **kwargs: [fn(*(tuple(x) + args), **kwargs)]
  else:
    wrapper = lambda x: [fn(*x)]

  # Proxy the type-hint information from the original function to this new
  # wrapped function.
  type_hints = get_type_hints(fn).with_defaults(
      typehints.decorators.IOTypeHints.from_callable(fn))
  if type_hints.input_types is not None:
    # TODO(BEAM-14052): ignore input hints, as we do not have enough
    # information to infer the input type hint of the wrapper function.
    pass
  output_hint = type_hints.simple_output_type(label)
  if output_hint:
    tagged = {
        k: typehints.Iterable[v]

View on GitHub (pinned to 12126d8942)