{"record":{"id":"9402f1c59c3f45f7","repo":"apache/beam","slug":"unable-to-encode-element","errorCode":null,"errorMessage":"Unable to encode element '","messagePattern":"Unable to encode element '","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/coders/DelegateCoder.java","lineNumber":119,"sourceCode":"   */\n  @Override\n  public void verifyDeterministic() throws NonDeterministicException {\n    coder.verifyDeterministic();\n  }\n\n  /**\n   * {@inheritDoc}\n   *\n   * @return a structural for a value of type {@code T} obtained by first converting to {@code\n   *     IntermediateT} and then obtaining a structural value according to the underlying coder.\n   */\n  @Override\n  public Object structuralValue(T value) {\n    try {\n      IntermediateT intermediate = toFn.apply(value);\n      return coder.structuralValue(intermediate);\n    } catch (Exception exn) {\n      throw new IllegalArgumentException(\n          \"Unable to encode element '\" + value + \"' with coder '\" + this + \"'.\", exn);\n    }\n  }\n\n  @Override\n  @SuppressWarnings(\"EqualsGetClass\")\n  public boolean equals(@Nullable Object o) {\n    if (o == null || this.getClass() != o.getClass()) {\n      return false;\n    }\n    DelegateCoder<?, ?> that = (DelegateCoder<?, ?>) o;\n    return Objects.equal(this.coder, that.coder)\n        && Objects.equal(this.toFn, that.toFn)\n        && Objects.equal(this.fromFn, that.fromFn);\n  }\n\n  @Override\n  public int hashCode() {","sourceCodeStart":101,"sourceCodeEnd":137,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/DelegateCoder.java#L101-L137","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Fix the DelegateCoder's conversion function so it accepts all values that can reach it (add null/domain handling).","Check the wrapped cause (exn.getCause()) for the underlying conversion failure and correct the input data.","Ensure the intermediate coder supports structuralValue for all convertible intermediates.","Validate elements before inserting them into the pipeline or before a GroupByKey."],"exampleFix":"// before\nDelegateCoder.of(Event.class, (Event e) -> e.getId().toLowerCase(), ...); // NPE on null id\n\n// after\nDelegateCoder.of(Event.class, (Event e) -> e.getId() == null ? \"\" : e.getId().toLowerCase(), ...);","handlingStrategy":"try-catch","validationCode":"Objects.requireNonNull(value, \"element must not be null\");\n// ensure conversion succeeds before pipeline use:\nT checked = value; // e.g. assert id != null before grouping","typeGuard":"boolean isValidEvent(Event e) { return e != null && e.getId() != null; }","tryCatchPattern":"try {\n  Object sv = coder.structuralValue(value);\n} catch (IllegalArgumentException e) {\n  LOG.error(\"Unconvertible element '\" + value + \"'\", e.getCause());\n  throw e;\n}","preventionTips":["Make DelegateCoder conversion functions total: handle nulls and out-of-domain inputs.","Validate element fields before GroupByKey/windowing stages.","Log the cause chain to find whether toFn or the intermediate coder failed."],"tags":["beam","java","coders","structural-value"],"backgroundTag":"type-mismatch","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-20T03:17:13.778Z"}