apache/beam · error · IllegalStateException

Unable to infer a coder for CombiningState and no Coder was

Error message

Unable to infer a coder for CombiningState and no Coder was specified. Please set a coder by either invoking StateSpecs.combining(Coder<AccumT> accumCoder, CombineFn<InputT, AccumT, OutputT> combineFn) or by registering the coder in the Pipeline's CoderRegistry.

What it means

A CombiningState spec created via StateSpecs.combining(combineFn) without an accumulator coder cannot infer one at finishSpecifying time. StateSpecs.CombiningStateSpec.finishSpecifying() throws IllegalStateException when accumCoder is null.

Source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/state/StateSpecs.java:499

    }

    @Override
    public <ResultT> ResultT match(Cases<ResultT> cases) {
      return cases.dispatchCombining(combineFn, accumCoder);
    }

    @SuppressWarnings("unchecked")
    @Override
    public void offerCoders(Coder[] coders) {
      if (this.accumCoder == null && coders[1] != null) {
        this.accumCoder = (Coder<AccumT>) coders[1];
      }
    }

    @Override
    public void finishSpecifying() {
      if (accumCoder == null) {
        throw new IllegalStateException(
            "Unable to infer a coder for"
                + " CombiningState and no Coder was specified."
                + " Please set a coder by either invoking"
                + " StateSpecs.combining(Coder<AccumT> accumCoder,"
                + " CombineFn<InputT, AccumT, OutputT> combineFn)"
                + " or by registering the coder in the Pipeline's CoderRegistry.");
      }
    }

    @Override
    public boolean equals(@Nullable Object obj) {
      if (obj == this) {
        return true;
      }

      if (!(obj instanceof CombiningStateSpec)) {
        return false;
      }

View on GitHub (pinned to 12126d8942)

Solutions

Use the two-argument factory: StateSpecs.combining(accumCoder, combineFn).
Register a coder for AccumT in the pipeline's CoderRegistry.
Simplify the accumulator type to one with an inferrable coder.

Example fix

// before
CombiningStateSpec<Long, Long, Long> spec = StateSpecs.combining(Sum.ofLongs());
// after
CombiningStateSpec<Long, Long, Long> spec = StateSpecs.combining(VarLongCoder.of(), Sum.ofLongs());

Defensive patterns

Strategy: validation

Validate before calling

if (accumCoder == null) {
  throw new IllegalStateException("Supply StateSpecs.combining(accumCoder, combineFn) with an explicit accumulator coder");
}

Try / catch

try {
  spec = StateSpecs.combining(fn);
} catch (IllegalStateException e) {
  if (e.getMessage().contains("CombiningState")) {
    spec = StateSpecs.combining(accumCoder, fn);
  } else throw e;
}

Prevention

Always use the (Coder, CombineFn) overload of StateSpecs.combining
Register a coder for your accumulator type
Keep accumulator types simple and coder-friendly

When it happens

Trigger: Calling StateSpecs.combining(CombineFn) (the overload without a Coder<AccumT>) where coder inference for the accumulator type AccumT fails.

Common situations: Custom CombineFn whose accumulator type is a custom class with no registered coder; using combining state with non-trivial accumulator types in pipelines without explicit coder registration.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

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