apache/beam · error · IllegalStateException

Unable to infer a coder for ValueState and no Coder was spec

Error message

Unable to infer a coder for ValueState and no Coder was specified. Please set a coder by either invoking StateSpecs.value(Coder<T> valueCoder) or by registering the coder in the Pipeline's CoderRegistry.

What it means

A ValueState spec created without an explicit coder (StateSpecs.value()) cannot infer how to serialize its values at pipeline-construction time. StateSpecs.ValueStateSpec.finishSpecifying() throws IllegalStateException when coder is still null after coder inference has run.

Source

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

    }

    @Override
    public <ResultT> ResultT match(Cases<ResultT> cases) {
      return cases.dispatchValue(coder);
    }

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

    @Override
    public void finishSpecifying() {
      if (coder == null) {
        throw new IllegalStateException(
            "Unable to infer a coder for ValueState and no Coder"
                + " was specified. Please set a coder by either invoking"
                + " StateSpecs.value(Coder<T> valueCoder) 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 ValueStateSpec)) {
        return false;
      }

      ValueStateSpec<?> that = (ValueStateSpec<?>) obj;

View on GitHub (pinned to 12126d8942)

Solutions

Pass an explicit coder: StateSpecs.value(myCoder).
Register the coder in the pipeline's CoderRegistry via pipeline.getCoderRegistry().registerCoderForType(...).
Make the value type use a codec/POJO type Beam can infer a coder for (e.g. Avro or annotated POJO).

Example fix

// before
ValueStateSpec<String> spec = StateSpecs.value();
// after
ValueStateSpec<String> spec = StateSpecs.value(StringUtf8Coder.of());

Defensive patterns

Strategy: validation

Validate before calling

if (valueCoder == null) {
  Coder<T> inferred = pipeline.getCoderRegistry().getCoder(TypeDescriptor.of(T.class)); // must not throw
}

Try / catch

try {
  StateSpecs.value(); // or pipeline.apply with state
} catch (IllegalStateException e) {
  if (e.getMessage().contains("Unable to infer a coder for ValueState")) {
    spec = StateSpecs.value(explicitCoder);
  } else throw e;
}

Prevention

Always pass an explicit coder to StateSpecs.value()
Register coders for custom types in the CoderRegistry at pipeline setup
Prefer Avro/annotated POJO types Beam can code automatically

When it happens

Trigger: Calling StateSpecs.value() with no Coder argument where the pipeline's CoderRegistry cannot infer a coder for the value type T (e.g. a custom POJO without a registered coder).

Common situations: Using a custom class as state value without registering a coder; using types not on the default coder registry; calling finishSpecifying outside a normal pipeline lifecycle where inference never ran.

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/8577ecee04994678. Report an issue: GitHub.