apache/beam · error · IllegalStateException

Unable to infer a coder for CombiningWithContextState and no

Error message

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

What it means

A CombiningWithContextState spec created without an explicit accumulator coder cannot infer one at finishSpecifying time. StateSpecs throws IllegalStateException when accumCoder is null, telling you to use StateSpecs.combiningWithContext(Coder, CombineFnWithContext).

Source

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

    public <ResultT> ResultT match(Cases<ResultT> cases) {
      throw new UnsupportedOperationException(
          String.format(
              "%s is for internal use only and does not support case dispatch",
              getClass().getSimpleName()));
    }

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

    @Override
    public void finishSpecifying() {
      if (accumCoder == null) {
        throw new IllegalStateException(
            "Unable to infer a coder for"
                + " CombiningWithContextState and no Coder was specified."
                + " Please set a coder by either invoking"
                + " StateSpecs.combiningWithcontext(Coder<AccumT> accumCoder,"
                + " CombineFnWithContext<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 CombiningWithContextStateSpec)) {
        return false;
      }

View on GitHub (pinned to 12126d8942)

Solutions

Use StateSpecs.combiningWithContext(accumCoder, combineFn) with an explicit coder.
Register a coder for AccumT in the pipeline's CoderRegistry.
Change the accumulator type to one with an inferrable coder.

Example fix

// before
StateSpecs.combiningWithContext(myContextualFn);
// after
StateSpecs.combiningWithContext(VarLongCoder.of(), myContextualFn);

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Always use the (Coder, CombineFnWithContext) overload
Register a coder for your accumulator type in the CoderRegistry
Verify coder inference in unit tests before running on a runner

When it happens

Trigger: Calling StateSpecs.combiningWithContext(CombineFnWithContext) (overload without Coder<AccumT>) where the accumulator type's coder cannot be inferred.

Common situations: Custom CombineFnWithContext with a custom accumulator class lacking a registered coder; pipelines where CoderRegistry inference fails for generic accumulator types.

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/5985edcbb273fbae. Report an issue: GitHub.