apache/beam · error · ValueError

combine_fn must be provided

Error message

combine_fn must be provided

What it means

CombiningValueStateSpec's constructor historically accepted (name, combine_fn) positionally; to stay backward compatible it now requires combine_fn either as the second positional argument or via the combine_fn keyword. If combine_fn is None and coder is also None, there is no way to derive the accumulation logic, so a ValueError is raised.

Solutions

1. Provide the combine_fn: CombiningValueStateSpec('name', sum) or CombiningValueStateSpec('name', combine_fn=sum)
2. If you intended the second argument as coder, use the combine_fn= keyword to make intent explicit
3. Use a callable or CombineFn instance (CombineFn.maybe_from_callable accepts both)

Example fix

// before
spec = CombiningValueStateSpec('sum')
// after
spec = CombiningValueStateSpec('sum', combine_fn=sum)

assert combine_fn is not None, 'CombiningValueStateSpec requires combine_fn'
spec = CombiningValueStateSpec('name', combine_fn=combine_fn)

try:
    spec = CombiningValueStateSpec('name', combine_fn=combine_fn)
except ValueError as e:
    raise ConfigError(f'combine_fn missing for state: {e}') from e

When it happens

Trigger: Calling CombiningValueStateSpec('name') with neither a second positional argument nor combine_fn=...; passing combine_fn=None explicitly while also omitting coder.

Common situations: Migrating code that previously passed (name, coder, combine_fn) and dropping the wrong argument; writing CombiningValueStateSpec(name, None) intending to fill it in later.

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

• A BigQuery table or a query must be specified
• A has been supplied to the model handler, but the required…
• artifact_location is not specified. Please specify the…
• bucket_boundaries requires length_fn to be set.
• coder is not of type Coder

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

Appendix: source

Thrown at sdks/python/apache_beam/transforms/userstate.py:143

    Args:
      name (str): The name by which the state is identified.
      coder (Coder): Coder specifying how to encode the values to be combined.
        May be inferred.
      combine_fn (``CombineFn`` or ``callable``): Function specifying how to
        combine the values passed to state.
    """
    # Avoid circular import.
    from apache_beam.transforms.core import CombineFn

    # We want the coder to be optional, but unfortunately it comes
    # before the non-optional combine_fn parameter, which we can't
    # change for backwards compatibility reasons.
    #
    # Instead, allow it to be omitted (by either passing two arguments
    # or combine_fn by keyword.)
    if combine_fn is None:
      if coder is None:
        raise ValueError('combine_fn must be provided')
      else:
        coder, combine_fn = None, coder
    self.combine_fn = CombineFn.maybe_from_callable(combine_fn)
    # The coder here should be for the accumulator type of the given CombineFn.
    if coder is None:
      coder = self.combine_fn.get_accumulator_coder()

    super().__init__(name, coder)

  def to_runner_api(
      self, context: 'PipelineContext') -> beam_runner_api_pb2.StateSpec:
    return beam_runner_api_pb2.StateSpec(
        combining_spec=beam_runner_api_pb2.CombiningStateSpec(
            combine_fn=self.combine_fn.to_runner_api(context),
            accumulator_coder_id=context.coders.get_id(self.coder)),
        protocol=beam_runner_api_pb2.FunctionSpec(
            urn=common_urns.user_state.BAG.urn))

View on GitHub (pinned to 12126d8942)