apache/beam · error · TypeError

FlatMapTuple can be used only with callable objects…

Error message

FlatMapTuple can be used only with callable objects. Received %r instead.

What it means

beam.FlatMapTuple unpacks tuple elements into fn's parameters and expects fn to return an iterable. Like Map/MapTuple, fn must be a plain callable; passing a DoFn instance or any non-callable raises this TypeError.

Solutions

1. Use beam.ParDo for DoFn instances.
2. Pass a plain callable (lambda, function, method, callable instance) to FlatMapTuple.
3. Don't invoke the function when passing it: beam.FlatMapTuple(my_fn).
4. Rewrite the DoFn's process body as a generator function and use that with FlatMapTuple.

Example fix

// before
beam.FlatMapTuple(MyDoFn())
// after
beam.FlatMapTuple(lambda k, v: [v] * k)
// or
beam.ParDo(MyDoFn())

if not callable(fn):
    raise TypeError('FlatMapTuple needs a callable, got %r' % (fn,))

def is_flatmaptuple_fn(fn):
    return callable(fn) and not isinstance(fn, DoFn)

try:
    out = pcoll | beam.FlatMapTuple(fn)
except TypeError as e:
    if 'callable objects' in str(e):
        out = pcoll | beam.ParDo(fn)
    else:
        raise

When it happens

Trigger: beam.FlatMapTuple(SomeDoFn()) or beam.FlatMapTuple(non_callable_object).

Common situations: Refactoring FlatMap to FlatMapTuple while keeping a DoFn; passing a class instance without __call__; mixing up ParDo and FlatMapTuple when handling KV/grouped PCollections.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Expected a callable object instead of: %r
• FlatMap can be used only with callable objects. Received %r…
• Map can be used only with callable objects. Received %r…
• MapTuple can be used only with callable objects. Received…
• @on_timer decorator expected callable.

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

Appendix: source

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

  (e.g. key-value pairs).

  Args:
    fn (callable): a callable object.
    *args: positional arguments passed to the transform callable.
    **kwargs: keyword arguments passed to the transform callable.

  Returns:
    ~apache_beam.pvalue.PCollection:
    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(

View on GitHub (pinned to 12126d8942)