apache/beam · error · TypeError

FlatMap can be used only with callable objects. Received %r…

Error message

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

What it means

beam.FlatMap accepts only plain callables; it wraps them in CallableWrapperDoFn itself. Passing a non-callable — most commonly a DoFn instance, which is only supported by ParDo — raises this TypeError.

Solutions

1. Use beam.ParDo(MyDoFn(...)) for DoFn instances instead of FlatMap.
2. If you meant a plain function, pass the function object itself (not its result): beam.FlatMap(my_fn) not beam.FlatMap(my_fn()).
3. Make sure the object is callable — classes are callable (they'll be instantiated), instances need __call__ or should be a function/method.
4. Extract the core logic of the DoFn into a plain function if you prefer FlatMap style.

Example fix

// before
beam.FlatMap(MyDoFn(args))
// after
beam.ParDo(MyDoFn(args))
// or, with a plain function:
beam.FlatMap(lambda x: [x, x])

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

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

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

When it happens

Trigger: beam.FlatMap(SomeDoFn()) or beam.FlatMap(non_callable_value) where fn lacks __call__.

Common situations: Migrating code between ParDo and FlatMap and forgetting to unwrap the DoFn; passing a class instead of an instance is fine but passing an instance that isn't callable fails; typos where a variable holding data is passed instead of a function.

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 and ParDo must return an iterable.
• FlatMapTuple can be used only with callable objects…
• Map can be used only with callable objects. Received %r…
• MapTuple can be used only with callable objects. Received…

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

Appendix: source

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

  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:`FlatMap` 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`.
  """
  label = 'FlatMap(%s)' % ptransform.label_from_callable(fn)
  if not callable(fn):
    raise TypeError(
        'FlatMap can be used only with callable objects. '
        'Received %r instead.' % (fn))

  pardo = ParDo(CallableWrapperDoFn(fn), *args, **kwargs)
  pardo.label = label

  return pardo


def Map(fn, *args, **kwargs):  # pylint: disable=invalid-name
  """:func:`Map` is like :func:`FlatMap` except its callable returns only a
  single element.

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

View on GitHub (pinned to 12126d8942)