{"record":{"id":"19a9934408449b47","repo":"apache/beam","slug":"unable-to-deserialize-record","errorCode":null,"errorMessage":"unable to deserialize record","messagePattern":"unable to deserialize record","errorType":"exception","errorClass":"CoderException","httpStatus":null,"severity":"error","filePath":"sdks/java/core/src/main/java/org/apache/beam/sdk/coders/SerializableCoder.java","lineNumber":202,"sourceCode":"\n  public Class<T> getRecordType() {\n    return type;\n  }\n\n  @Override\n  public void encode(T value, OutputStream outStream) throws IOException {\n    ObjectOutputStream oos = new ObjectOutputStream(outStream);\n    oos.writeObject(value);\n    oos.flush();\n  }\n\n  @Override\n  public T decode(InputStream inStream) throws IOException, CoderException {\n    try {\n      ObjectInputStream ois = new ObjectInputStream(inStream);\n      return type.cast(ois.readObject());\n    } catch (ClassNotFoundException e) {\n      throw new CoderException(\"unable to deserialize record\", e);\n    }\n  }\n\n  /**\n   * {@inheritDoc}\n   *\n   * @throws NonDeterministicException always. Java serialization is not deterministic with respect\n   *     to {@link Object#equals} for all types.\n   */\n  @Override\n  public void verifyDeterministic() throws NonDeterministicException {\n    throw new NonDeterministicException(this, \"Java Serialization may be non-deterministic.\");\n  }\n\n  @Override\n  @SuppressWarnings(\"EqualsGetClass\")\n  public boolean equals(@Nullable Object other) {\n    return !(other == null || getClass() != other.getClass())","sourceCodeStart":184,"sourceCodeEnd":220,"githubUrl":"https://github.com/apache/beam/blob/12126d8942aaf848030c478b4c6a28c6af861c66/sdks/java/core/src/main/java/org/apache/beam/sdk/coders/SerializableCoder.java#L184-L220","documentation":"SerializableCoder.decode() uses Java ObjectInputStream to deserialize; if the class of the serialized object is not on the classpath (ClassNotFoundException) it wraps it in a CoderException 'unable to deserialize record'. This typically means the writer and reader environments have different class versions or the class was renamed/moved.","triggerScenarios":"Decoding bytes produced in a different job/environment where the serialized class has been renamed, moved packages, or removed; running an updated pipeline against old state; fat-jar shading changing class names (serialVersionUID/class name mismatch).","commonSituations":"Class refactoring between pipeline versions; streaming job resume after a deploy where the class changed; shaded/relocated classes breaking ObjectInputStream resolution.","solutions":["Restore the original fully-qualified class name (and serialVersionUID) so ObjectInputStream can resolve it","Re-run the pipeline from the source instead of resuming from serialized state","Add a serialVersionUID and avoid renaming/moving classes between releases","If shading, configure the shade plugin to keep the class name stable, or use a non-Java-serialization coder (Avro/Row)"],"exampleFix":"// before\nclass MyRecord { } // renamed from com.old.pkg.MyRecord; old state unreadable\n// after\nclass MyRecord implements Serializable {\n  private static final long serialVersionUID = 1L;\n}\n// keep FQCN stable, or re-run from source","handlingStrategy":"try-catch","validationCode":"// Check the serialized class is resolvable: Class.forName(\"com.pkg.MyRecord\") in the reading job","typeGuard":"null","tryCatchPattern":"try { T v = coder.decode(in); } catch (CoderException e) { /* ClassNotFoundException cause: class missing/renamed; re-run from source */ }","preventionTips":["Declare serialVersionUID and keep class FQCNs stable across releases","Avoid moving/renaming Serializable classes used in pipeline state","Prefer explicit coders (Avro/Row) over Java serialization for durable data"],"tags":["java","beam","deserialization","classpath"],"backgroundTag":"class-not-found","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"}