{"record":{"id":"230c631b3f8a3791","repo":"apache/beam","slug":"unknowncoderwrapper-was-used-to-perform-an-actual-encoding","errorCode":null,"errorMessage":"`UnknownCoderWrapper` was used to perform an actual encoding in the Java SDK. Potentially a `PCollection` that was generated by a cross-language transform, that uses a coder that is not available in the Java SDK, is being consumed by a Java transform. Please make sure that cross-language transforms at the language boundary use Beam portable coders.","messagePattern":"`UnknownCoderWrapper` was used to perform an actual encoding in the Java SDK\\. Potentially a `PCollection` that was generated by a cross-language transform, that uses a coder that is not available in the Java SDK, is being consumed by a Java transform\\. Please make sure that cross-language transforms at the language boundary use Beam portable coders\\.","errorType":"exception","errorClass":"CoderException","httpStatus":null,"severity":"critical","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/UnknownCoderWrapper.java","lineNumber":45,"sourceCode":" * Represents a {@code Coder} that is not defined in Java SDK, for example, a coder that is\n * available in an external SDK that cannot be fully interpretted in the Java SDK.\n */\npublic class UnknownCoderWrapper extends AtomicCoder<Object> {\n  private String urn;\n  private byte[] payload;\n\n  private UnknownCoderWrapper(String urn, byte[] payload) {\n    this.urn = urn;\n    this.payload = payload;\n  }\n\n  public static UnknownCoderWrapper of(String urn, byte[] payload) {\n    return new UnknownCoderWrapper(urn, payload);\n  }\n\n  @Override\n  public void encode(Object value, OutputStream outStream) throws CoderException, IOException {\n    throw new CoderException(\n        \"`UnknownCoderWrapper` was used to perform an actual encoding in the Java SDK. \"\n            + \"Potentially a `PCollection` that was generated by a cross-language transform, \"\n            + \"that uses a coder that is not available in the Java SDK, is being consumed by a Java\"\n            + \" transform. Please make sure that cross-language transforms at the language \"\n            + \"boundary use Beam portable coders.\");\n  }\n\n  @Override\n  public Object decode(InputStream inStream) throws CoderException, IOException {\n    throw new CoderException(\n        \"`UnknownCoderWrapper` was used to perform an actual decoding in the Java SDK. \"\n            + \"Potentially a Java transform is being followed by a cross-language transform that \"\n            + \"uses a coder that is not available in the Java SDK. Please make sure that Python \"\n            + \"transforms at the multi-language boundary use Beam portable coders.\");\n  }\n\n  public String getUrn() {\n    return urn;","sourceCodeStart":27,"sourceCodeEnd":63,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/util/construction/UnknownCoderWrapper.java#L27-L63","documentation":"UnknownCoderWrapper is a placeholder coder created during pipeline graph translation when a cross-language (e.g. Python) transform produces a PCollection whose coder the Java SDK cannot resolve. It exists only to keep the graph intact; calling its encode() intentionally throws this CoderException because the Java SDK has no real implementation for that coder.","triggerScenarios":"A Java transform consumes the output of a cross-language transform whose PCollection uses a non-portable (language-specific) coder, and the runtime actually attempts to serialize an element with UnknownCoderWrapper.encode(Object, OutputStream).","commonSituations":"See trigger scenarios.","solutions":["Make the cross-language transform's output use a Beam portable coder (a coder with a well-known URN resolvable in both SDKs).","If you own the Python transform, wrap custom coders with coders registry entries that map to portable URNs instead of language-specific coders.","On the Java side, register/re-map the unknown coder URN to a known Java coder in the coder registry used by expansion.","Upgrade both SDKs to a version that supports the coder; verify the expansion service and pipeline environments use compatible Beam versions."],"exampleFix":"// before (Python side): custom non-portable coder on output PCollection\ncustom_pcoll = beam.Map(my_fn).with_output_types(MyCustomType)\n// after: annotate the transform to use a portable coder at the boundary\ncustom_pcoll = beam.Map(my_fn).with_output_types(MyCustomType)\n# and register: MyCustomCoder implements to_type_hint/to_runner_api with a portable URN","handlingStrategy":"validation","validationCode":"// Before consuming a cross-language output in Java, verify the coder is not the unknown wrapper\nCoder<?> c = output.getCoder();\nif (c instanceof UnknownCoderWrapper) {\n  throw new IllegalStateException(\n      \"Cross-language output uses an unknown coder URN \" + ((UnknownCoderWrapper) c).getUrn()\n      + \"; register a portable Java coder before consuming.\");\n}","typeGuard":"boolean isUnknownCoder(Coder<?> coder) {\n  return coder instanceof org.apache.beam.sdk.util.construction.UnknownCoderWrapper;\n}","tryCatchPattern":"try {\n  output.apply(\"JavaConsumer\", javaTransform);\n} catch (CoderException e) {\n  if (String.valueOf(e.getMessage()).contains(\"UnknownCoderWrapper\")) {\n    // re-map the coder URN to a concrete Java coder, then resubmit\n  }\n  throw e;\n}","preventionTips":["Always use Beam portable (URN-registered) coders on PCollections crossing the language boundary.","Before wiring a Python expansion's output into Java, print/inspect the resolved coder.","Keep Java and Python SDK versions aligned so coder URNs are mutually registered.","Test cross-language expansions in a small pipeline before production use."],"tags":["cross-language","coder","serialization","java","portability"],"backgroundTag":"unsupported-operation","analyzedSha":"12126d8942aaf848030c478b4c6a28c6af861c66","analyzedAt":"2026-09-13T01:50:10.254Z","contentChangedAt":"2026-09-13T01:50:10.254Z","schemaVersion":2},"datasetVersion":"2026-09-14T16:17:12.679Z"}