apache/beam · error · IllegalStateException

Unable to infer a coder for MultimapState and no Coder was…

Error message

Unable to infer a coder for MultimapState and no Coder was specified. Please set a coder by either invoking StateSpecs.multimap(Coder<K> keyCoder, Coder<V> valueCoder) or by registering the coder in the Pipeline's CoderRegistry.

What it means

A MultimapState spec created without key and/or value coders cannot infer both at finishSpecifying time. MultimapStateSpec.finishSpecifying() throws IllegalStateException when keyCoder or valueCoder is null.

Solutions

  1. Pass both coders: StateSpecs.multimap(keyCoder, valueCoder).
  2. Register coders for K and V in the pipeline's CoderRegistry.
  3. If converting from a MapStateSpec, ensure the original map spec had explicit coders.

Example fix

// before
MultimapStateSpec<String, Long> spec = StateSpecs.multimap();
// after
MultimapStateSpec<String, Long> spec = StateSpecs.multimap(StringUtf8Coder.of(), VarLongCoder.of());
Defensive patterns

Strategy: validation

Validate before calling

if (keyCoder == null || valueCoder == null) {
  throw new IllegalStateException("Supply StateSpecs.multimap(keyCoder, valueCoder) with explicit coders");
}

Try / catch

try {
  spec = StateSpecs.multimap();
} catch (IllegalStateException e) {
  if (e.getMessage().contains("MultimapState")) {
    spec = StateSpecs.multimap(keyCoder, valueCoder);
  } else throw e;
}

Prevention

When it happens

Trigger: Calling StateSpecs.multimap() (no-arg overload) where inference fails for the key type K or the value type V.

Common situations: Multimaps with custom key or value classes lacking registered coders; specs converted from map specs via convertToMultimapSpec where coders were never supplied.

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

Appendix: source

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

    public <ResultT> ResultT match(Cases<ResultT> cases) {
      return cases.dispatchMultimap(keyCoder, valueCoder);
    }

    @SuppressWarnings("unchecked")
    @Override
    public void offerCoders(Coder[] coders) {
      if (this.keyCoder == null && coders[0] != null) {
        this.keyCoder = (Coder<K>) coders[0];
      }
      if (this.valueCoder == null && coders[1] != null) {
        this.valueCoder = (Coder<V>) coders[1];
      }
    }

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

      MultimapStateSpec<?, ?> that = (MultimapStateSpec<?, ?>) obj;

View on GitHub (pinned to 12126d8942)