apache/beam · error · TypeError

Side inputs must have defaults for FlatMapTuple.

Error message

Side inputs must have defaults for FlatMapTuple.

What it means

FlatMapTuple spreads the input tuple plus side inputs positionally into fn. As with MapTuple, every side input must map onto a fn parameter with a default value (since deferred side inputs can arrive as fewer positional args). Fewer defaults than side inputs raises this TypeError.

Solutions

  1. Add default values to fn's parameters corresponding to each side input: def fn(k, v, extra=None, cfg=None): ...
  2. Pass fewer side inputs, matching existing defaulted parameters.
  3. Switch to beam.ParDo if you need DoFn-style side input access without defaults.
  4. Use keyword side inputs mapped to fn's keyword-with-default parameters instead of positional.

Example fix

// before
def fn(k, v, limit): ...  # missing default
beam.FlatMapTuple(fn, 'limit_label')
// after
def fn(k, v, limit=10): ...
beam.FlatMapTuple(fn, 'limit_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)
assert len(defaults) >= len(args) + len(kwargs), 'need a defaulted param per side input for FlatMapTuple'

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.FlatMapTuple(fn, *side_labels)
except TypeError as e:
    if 'defaults for FlatMapTuple' in str(e):
        raise ValueError('Add default values to fn params for each side input') from e
    raise

Prevention

When it happens

Trigger: beam.FlatMapTuple(fn, side_label1, side_label2) where fn has fewer default-valued parameters than 2 side inputs.

Common situations: Adding side inputs (AsIter/AsDict/AsSingleton) without adding defaulted params to the function; refactoring from ParDo (where side inputs are declared via __process__) to FlatMapTuple; team conventions mismatch on how side inputs bind.

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/98429d89fbc2dae8. Report an issue: GitHub.

Appendix: source

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

    A :class:`~apache_beam.pvalue.PCollection` containing the
    :func:`FlatMapTuple` 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(
        'FlatMapTuple can be used only with callable objects. '
        'Received %r instead.' % (fn))

  label = 'FlatMapTuple(%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 FlatMapTuple.')

  if defaults or args or kwargs:
    wrapper = lambda x, *args, **kwargs: fn(*(tuple(x) + args), **kwargs)
  else:
    wrapper = lambda x: fn(*tuple(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:
    wrapper = with_output_types(
        _strip_output_annotations(output_hint, strip_tagged_output=False),

View on GitHub (pinned to 12126d8942)