apache/beam · error · IllegalStateException

Unable to infer a coder for OrderedListState and no Coder wa

Error message

Unable to infer a coder for OrderedListState and no Coder was specified. Please set a coder by either invoking StateSpecs.orderedListState(Coder<K> elemCoder), specifying a schema,  or by registering the coder in the Pipeline's CoderRegistry.

What it means

An OrderedListState spec created without an element coder and without a schema cannot infer one at finishSpecifying time. OrderedListStateSpec.finishSpecifying() throws IllegalStateException when elemCoder is null.

Source

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

    }

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

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

    @Override
    public void finishSpecifying() {
      if (elemCoder == null) {
        throw new IllegalStateException(
            "Unable to infer a coder for OrderedListState and no Coder"
                + " was specified. Please set a coder by either invoking"
                + " StateSpecs.orderedListState(Coder<K> elemCoder), specifying a schema,  or by registering the"
                + " coder in the Pipeline's CoderRegistry.");
      }
    }

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

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

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

View on GitHub (pinned to 12126d8942)

Solutions

Pass an explicit coder: StateSpecs.orderedListState(elemCoder).
Specify a schema for the element type so a coder can be derived.
Register a coder for the element type K in the pipeline's CoderRegistry.

Example fix

// before
OrderedListStateSpec<MyRecord> spec = StateSpecs.orderedListState();
// after
OrderedListStateSpec<MyRecord> spec = StateSpecs.orderedListState(myRecordCoder);

Defensive patterns

Strategy: validation

Validate before calling

if (elemCoder == null && schema == null) {
  throw new IllegalStateException("Supply StateSpecs.orderedListState(elemCoder) or a schema for the element type");
}

Try / catch

try {
  spec = StateSpecs.orderedListState();
} catch (IllegalStateException e) {
  if (e.getMessage().contains("OrderedListState")) {
    spec = StateSpecs.orderedListState(elemCoder);
  } else throw e;
}

Prevention

Provide either an explicit coder or a schema for ordered-list elements
Register element coders in the CoderRegistry
Check that element types are schema/coder compatible

When it happens

Trigger: Calling StateSpecs.orderedListState() with no coder where element coder inference fails and no schema was specified.

Common situations: Ordered lists of custom record types without registered coders; using schema-based ordered lists but forgetting to supply either coder or schema.

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/56d5d2c4e1c0d203. Report an issue: GitHub.