{"record":{"id":"25812e95c80ec74f","repo":"apache/beam","slug":"unable-to-serialize-value","errorCode":null,"errorMessage":"unable to serialize {value}","messagePattern":"unable to serialize (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/util/SerializableUtils.java","lineNumber":59,"sourceCode":"@SuppressWarnings({\n  \"nullness\", // TODO(https://github.com/apache/beam/issues/20497)\n  \"rawtypes\"\n})\npublic class SerializableUtils {\n  /**\n   * Serializes the argument into an array of bytes, and returns it.\n   *\n   * @throws IllegalArgumentException if there are errors when serializing\n   */\n  public static byte[] serializeToByteArray(Serializable value) {\n    try {\n      ByteArrayOutputStream buffer = new ByteArrayOutputStream();\n      try (ObjectOutputStream oos = new ObjectOutputStream(new SnappyOutputStream(buffer))) {\n        oos.writeObject(value);\n      }\n      return buffer.toByteArray();\n    } catch (IOException exn) {\n      throw new IllegalArgumentException(\"unable to serialize \" + value, exn);\n    }\n  }\n\n  /**\n   * Deserializes an object from the given array of bytes, e.g., as serialized using {@link\n   * #serializeToByteArray}, and returns it.\n   *\n   * @throws IllegalArgumentException if there are errors when deserializing, using the provided\n   *     description to identify what was being deserialized\n   */\n  public static Object deserializeFromByteArray(byte[] encodedValue, String description) {\n    try {\n      try (ObjectInputStream ois =\n          new ContextualObjectInputStream(\n              new SnappyInputStream(new ByteArrayInputStream(encodedValue)))) {\n        return ois.readObject();\n      }\n    } catch (IOException | ClassNotFoundException exn) {","sourceCodeStart":41,"sourceCodeEnd":77,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/util/SerializableUtils.java#L41-L77","documentation":"serializeToByteArray serializes a Serializable object with ObjectOutputStream (Snappy-compressed). Any IOException during writing is rethrown as IllegalArgumentException 'unable to serialize <value>'. This usually means the object graph contains a non-serializable field (NotSerializableException is an IOException subclass) rather than an I/O problem.","triggerScenarios":"Calling SerializableUtils.serializeToByteArray(value) or clone(value) where value (or a nested field/lambda capture) does not implement Serializable, e.g. capturing a DoFn-unfriendly object in an anonymous class.","commonSituations":"Passing lambdas or anonymous inner classes that capture non-serializable objects (connection handles, builders, non-serializable library types) into Beam transforms that clone/serialize them.","solutions":["Inspect the cause (NotSerializableException names the offending class) and make that class implement Serializable.","Mark non-serializable fields transient and reconstruct them lazily (or in readObject/readResolve).","Remove the non-serializable capture from lambdas/anonymous classes; pass only serializable data or look up resources at runtime.","For third-party types, wrap them in a custom Serializable adapter or serialize only the data needed to rebuild them."],"exampleFix":"// before\nnew DoFn<String, String>() { String helper = someNonSerializableHelper; ... }\n// after\nclass MyFn extends DoFn<String, String> {\n  transient Helper helper; // rebuilt in @Setup\n  @Setup void setup() { helper = new Helper(); }\n}","handlingStrategy":"type-guard","validationCode":"if (!java.io.Serializable.class.isInstance(value)) { throw new IllegalArgumentException(value.getClass() + \" is not Serializable\"); }","typeGuard":"static <T> boolean isSerializable(T v) { return v instanceof java.io.Serializable; }","tryCatchPattern":"try { byte[] b = SerializableUtils.serializeToByteArray(value); } catch (IllegalArgumentException e) { LOG.error(\"non-serializable: {}\", e.getCause()); throw e; }","preventionTips":["Ensure all DoFn fields and lambda captures are Serializable or transient.","Rebuild resources (clients, connections) in @Setup instead of serializing them.","Run ensureSerializable(value) in unit tests on pipeline objects."],"tags":["java","beam","serialization","not-serializable"],"backgroundTag":"json-serialization-failed","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"}