apache/beam · error · IllegalArgumentException

Unable to encode element '

Error message

Unable to encode element '

What it means

DelegateCoder.structuralValue applies the 'to' function and delegates to the intermediate coder; any exception in that chain is rethrown as IllegalArgumentException with the element's toString and the coder. It usually reflects a value that cannot be converted to the intermediate type or fails structural-value extraction on the delegate coder.

Solutions

1. Fix the DelegateCoder's conversion function so it accepts all values that can reach it (add null/domain handling).
2. Check the wrapped cause (exn.getCause()) for the underlying conversion failure and correct the input data.
3. Ensure the intermediate coder supports structuralValue for all convertible intermediates.
4. Validate elements before inserting them into the pipeline or before a GroupByKey.

Example fix

// before
DelegateCoder.of(Event.class, (Event e) -> e.getId().toLowerCase(), ...); // NPE on null id

// after
DelegateCoder.of(Event.class, (Event e) -> e.getId() == null ? "" : e.getId().toLowerCase(), ...);

Objects.requireNonNull(value, "element must not be null");
// ensure conversion succeeds before pipeline use:
T checked = value; // e.g. assert id != null before grouping

boolean isValidEvent(Event e) { return e != null && e.getId() != null; }

try {
  Object sv = coder.structuralValue(value);
} catch (IllegalArgumentException e) {
  LOG.error("Unconvertible element '" + value + "'", e.getCause());
  throw e;
}

When it happens

Trigger: Calling structuralValue (directly or via grouping/windowing that requires structural keys) on a DelegateCoder whose toFn.apply(value) throws, or whose intermediate coder's structuralValue throws for the converted value.

Common situations: GBKO grouping on custom types wrapped in DelegateCoder where the conversion function rejects some inputs (null fields, out-of-domain values); type erasure causing ClassCastException inside toFn.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

• cannot encode a null Byte
• cannot encode a null Double
• cannot encode a null Float
• cannot encode a null Map
• cannot encode a null ReadableDuration

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

Appendix: source

Thrown at sdks/java/core/src/main/java/org/apache/beam/sdk/coders/DelegateCoder.java:119

   */
  @Override
  public void verifyDeterministic() throws NonDeterministicException {
    coder.verifyDeterministic();
  }

  /**
   * {@inheritDoc}
   *
   * @return a structural for a value of type {@code T} obtained by first converting to {@code
   *     IntermediateT} and then obtaining a structural value according to the underlying coder.
   */
  @Override
  public Object structuralValue(T value) {
    try {
      IntermediateT intermediate = toFn.apply(value);
      return coder.structuralValue(intermediate);
    } catch (Exception exn) {
      throw new IllegalArgumentException(
          "Unable to encode element '" + value + "' with coder '" + this + "'.", exn);
    }
  }

  @Override
  @SuppressWarnings("EqualsGetClass")
  public boolean equals(@Nullable Object o) {
    if (o == null || this.getClass() != o.getClass()) {
      return false;
    }
    DelegateCoder<?, ?> that = (DelegateCoder<?, ?>) o;
    return Objects.equal(this.coder, that.coder)
        && Objects.equal(this.toFn, that.toFn)
        && Objects.equal(this.fromFn, that.fromFn);
  }

  @Override
  public int hashCode() {

View on GitHub (pinned to 12126d8942)