apache/beam · error · TypeError

CombineGlobally can be used only with combineFn objects…

Error message

CombineGlobally can be used only with combineFn objects. Received %r instead.

What it means

CombineGlobally requires its fn argument to be either a CombineFn instance or a callable (which is then wrapped into a CombineFn). This TypeError fires when the argument is neither, guarding against passing random objects such as DoFns or partially-built transforms.

Solutions

Pass a CombineFn subclass instance implementing create_accumulator/add_input/merge_accumulators/extract_output
Or pass a plain callable like sum or lambda xs: ... that takes an iterable
Verify the argument type before constructing: isinstance(fn, CombineFn) or callable(fn)

Example fix

// before
beam.CombineGlobally(MySumDoFn())
// after
beam.CombineGlobally(sum)  # or a CombineFn subclass instance

Defensive patterns

Strategy: type-guard

Validate before calling

if not (isinstance(fn, CombineFn) or callable(fn)):
    raise TypeError('CombineGlobally requires a CombineFn or callable, got %r' % (fn,))

Type guard

def is_combinable(fn) -> bool:
    return isinstance(fn, CombineFn) or callable(fn)

Try / catch

try:
    step = beam.CombineGlobally(fn)
except TypeError as e:
    if 'CombineGlobally can be used only with combineFn' in str(e):
        step = beam.CombineGlobally(wrap_into_combine_fn(fn))
    else:
        raise

Prevention

Use beam.CombineFn subclasses for complex aggregations
Do not pass DoFns to combine transforms; they belong to ParDo
Add unit tests constructing each transform with the intended argument type

When it happens

Trigger: Calling CombineGlobally(some_do_fn_or_object) where the object is not a CombineFn and has no __call__, e.g. passing a DoFn instance, a string, or a module.

Common situations: Copy-paste from a ParDo example into a combine step, or confusion between combine functions and DoFns when refactoring pipeline code.

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

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

Appendix: source

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

    ~apache_beam.pvalue.PCollection: A single-element
    :class:`~apache_beam.pvalue.PCollection` containing the main output of
    the :class:`CombineGlobally` transform.

  Note that the positional and keyword arguments will be processed in order
  to detect :class:`~apache_beam.pvalue.PValue` s that will be computed as side
  inputs to the transform.
  During pipeline execution whenever the :class:`CombineFn` object gets executed
  (i.e. any of the :class:`CombineFn` methods get called), the
  :class:`~apache_beam.pvalue.PValue` arguments will be replaced by their
  actual value in the exact position where they appear in the argument lists.
  """
  has_defaults = True
  as_view = False
  fanout = None  # type: typing.Optional[int]

  def __init__(self, fn, *args, **kwargs):
    if not (isinstance(fn, CombineFn) or callable(fn)):
      raise TypeError(
          'CombineGlobally can be used only with combineFn objects. '
          'Received %r instead.' % (fn))

    super().__init__()
    self.fn = fn
    self.args = args
    self.kwargs = kwargs

  def display_data(self):
    return {
        'combine_fn': DisplayDataItem(
            self.fn.__class__, label='Combine Function'),
        'combine_fn_dd': self.fn,
    }

  def default_label(self):
    if self.fanout is None:
      return '%s(%s)' % (

View on GitHub (pinned to 12126d8942)