apache/beam · error · IllegalStateException

Unable to construct coder

Error message

Unable to construct coder %s. Expected translation context %s but received %s.

What it means

StateBackedIterable.Coder.fromComponents throws this IllegalStateException when the Coder.Context passed during coder construction is not a StateBackedIterableTranslationContext. The coder requires the translation context to carry a cache token, state client, and current instruction ID; receiving a plain context means translation was set up incorrectly.

Solutions

1. Ensure translation runs through the Beam Fn harness path that supplies StateBackedIterableTranslationContext
2. Check runner and SDK harness versions match (context class/package must be identical)
3. In tests, build the context via the harness helpers rather than a bare Coder.Context
4. Compare context.getClass().getName() in the message against the expected class name to spot duplicate-classloader issues

Example fix

// before
new StateBackedIterable.Coder<>(new Coder.Context(true), cache, client, elemCoder);
// after: use the harness translation context
StateBackedIterableTranslationContext ctx =
    new StateBackedIterableTranslationContext(cache, client, instructionId);
new StateBackedIterable.Coder<>(ctx, cache, client, elemCoder);

if (!(context instanceof StateBackedIterableTranslationContext)) {
  throw new IllegalArgumentException("wrong coder context: " + context.getClass());
}

boolean hasTranslationContext(Coder.Context ctx) {
  return ctx instanceof StateBackedIterableTranslationContext;
}

try {
  return StateBackedIterable.Coder.of(cache, client, instructionId, elemCoder);
} catch (IllegalStateException e) {
  throw new IllegalStateException("state-backed coder needs harness translation context", e);
}

When it happens

Trigger: Translating/constructing a StateBackedIterable coder in a context that is not an instance of StateBackedIterableTranslationContext — i.e. code path bypassing the harness's state-backed-iterable translation setup.

Common situations: Runner not registering the state-backed iterable translation context; custom pipeline visitors or tests constructing the coder directly with new Coder.Context(false); Beam version mismatch where the context class changed.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• A function must be provided to convert the input type into…
• A PValue contained in
• A schema was provided without a data format (or viceversa)…
• All inherited interfaces of
• An unsupported type of cache was passed in. Received

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

Appendix: source

Thrown at sdks/java/harness/src/main/java/org/apache/beam/fn/harness/state/StateBackedIterable.java:353

    @Override
    public List<? extends org.apache.beam.sdk.coders.Coder<?>> getComponents(
        StateBackedIterable.Coder<?> from) {
      return Collections.<org.apache.beam.sdk.coders.Coder<?>>singletonList(from.getElemCoder());
    }

    @Override
    public StateBackedIterable.Coder<?> fromComponents(
        List<org.apache.beam.sdk.coders.Coder<?>> components,
        byte[] payload,
        TranslationContext context) {
      if (context instanceof StateBackedIterableTranslationContext) {
        return new StateBackedIterable.Coder<>(
            ((StateBackedIterableTranslationContext) context).getCache(),
            ((StateBackedIterableTranslationContext) context).getStateClient(),
            ((StateBackedIterableTranslationContext) context).getCurrentInstructionId(),
            Iterables.getOnlyElement(components));
      } else {
        throw new IllegalStateException(
            String.format(
                "Unable to construct coder %s. Expected translation context %s but received %s.",
                STATE_BACKED_ITERABLE_CODER_URN,
                StateBackedIterableTranslationContext.class.getName(),
                context.getClass().getName()));
      }
    }
  }
}

View on GitHub (pinned to 12126d8942)