serialVersionUID in Java: Class Version Compatibility - Quiz

serialVersionUID is the version number of a serializable class: a private static final long serialVersionUID field. Static fields are normally not serialized, but this number does get into the stream — not as object state, but as part of the class descriptor that ObjectOutputStream writes before the object data.

During deserialization, ObjectInputStream reads the class descriptor from the stream (the name, the serialVersionUID, the fields with their types), finds the class with the same name on the classpath and compares the numbers:

• the numbers differ — InvalidClassException: local class incompatible; the fields are not even compared;
• the numbers match — fields are matched by name: a field present both in the stream and in the class gets the value from the stream; a field present only in the class gets its default value (null, 0, false); a field present only in the stream is skipped;
• if a field with the same name has changed its type, reading still fails.

A matching number is the developer's promise: "the new version of the class can read the data of the old one." It does not guarantee correct values: if the meaning of a field changed (for example, price used to store dollars and now stores cents), the data is read without errors but with wrong values. Change the number when the meaning of the data changes, not only its structure.

The code compiles, but the JVM computes a default number — a SHA-1 hash of the class structure. The calculation includes the class name and modifiers, the names of the interfaces, all fields except private static and private transient ones, whether there is a static initializer, and all non-private constructors and methods. That is why the number changes after edits that do not touch the data: you add a public method, make the class final or add an interface — and the old file can no longer be read (InvalidClassException: local class incompatible). On top of that, because of synthetic members of nested and anonymous classes, javac and the Eclipse compiler can compute different numbers for the same source. So the number is declared explicitly.

Any long value works (negative ones included): the JVM only checks that the numbers match.

• A new class that has never been serialized — 1L: it reads as "version 1" and is easy to bump to 2L after an incompatible change.
• An old class without serialVersionUID whose data already sits in files or a cache — the number the JVM used to compute. Take it from the InvalidClassException message (the stream classdesc value) or run serialver -classpath . Cat on the old version of the class; IntelliJ IDEA can also generate it with a quick-fix. If you declare 1L here, you break reading of the old data yourself.

java.io.InvalidClassException is a subclass of IOException thrown by ObjectInputStream when the class on the classpath does not match the data in the stream. The text after the class name tells you the cause:

• local class incompatible: stream classdesc serialVersionUID = X, local class serialVersionUID = Y — the version numbers differ: the field is not declared and the class has changed, or the number was changed by hand. If the changes are compatible, declare the old number X from the message in the class.
• incompatible types for field age — a field with the same name changed its primitive type (int → long) or a primitive was replaced with a reference type. Restore the type, or add a new field with a different name and copy the value in readObject().
• class invalid for deserialization — the class no longer implements Serializable; bring back implements Serializable.
• Serializable incompatible with Externalizable — the class was switched from one interface to the other; old data cannot be read this way, a separate migration is needed.
• no valid constructor — the nearest non-serializable superclass has no accessible no-arg constructor; add one.

Changing the reference type of a field (for example, String → StringBuilder) produces a different exception: ClassCastException: cannot assign instance of java.lang.String to field Cat.name of type java.lang.StringBuilder. The cause and the fix are the same as for incompatible types for field. And after a class is renamed or moved to another package, reading fails with ClassNotFoundException: the stream stores the fully qualified class name.

According to the Java Object Serialization Specification (chapter 5.6), these changes are compatible: adding a field (it gets its default value, for example null), adding and removing methods and constructors, changing a field's access modifier, making a field non-static/non-transient, adding and removing writeObject()/readObject(), adding a class to the hierarchy or removing one from it. All of this works only when serialVersionUID is declared explicitly and has not changed.

Incompatible: changing a field's type (int → long gives InvalidClassException: incompatible types for field age even with a matching number), making a field static/transient, renaming a field, moving the class to another package, moving it up or down the hierarchy, removing Serializable, switching to Externalizable. Deleting a field is formally incompatible too: the new version reads old data, but an old version reading new data gets the default value in that field.

If the default value does not suit a new field, set it in readObject():

@Serial
private void readObject(ObjectInputStream in) throws IOException, ClassNotFoundException {
    in.defaultReadObject(); // standard reading of the fields
    if (color == null) {
        color = "unknown";
    }
}

For incompatible changes: keep the old field and add a new one (long ageInDays next to int age, filled in readObject()), convert the old files with a program that uses the old version of the class, or deliberately bump the number to 2L if the old data is no longer needed. For long-lived data, JSON (Jackson, Gson) or Protobuf is safer.

• Hierarchy. serialVersionUID is not inherited: the JVM looks for the field only in the class itself. The stream contains descriptors of the object's class and of all its serializable superclasses, and each one is checked separately. If Cat extends Animal and both are Serializable, declare the number in each; changing the number in Animal breaks reading of all saved Cat objects.
• enum values are serialized by constant name, and their serialVersionUID is always 0L; the JVM ignores a declaration.
• record classes (Java 16+) are deserialized through the canonical constructor, and the serialVersionUID matching check is waived for them — you don't have to declare the number.

The warning usually shows up on a custom exception or a Swing class: Throwable and Component implement Serializable, so all their subclasses are serializable too. Eclipse says The serializable class MyException does not declare a static final serialVersionUID field of type long, javac with -Xlint:serial says serializable class MyException has no definition of serialVersionUID, and IntelliJ IDEA has the Serializable class without 'serialVersionUID' inspection (off by default).

If objects of the class are never serialized, you can suppress the warning with @SuppressWarnings("serial"). But declaring @Serial private static final long serialVersionUID = 1L; is almost as short, and it protects the class if someone starts serializing it later (the exception is sent over RMI or stored in an HTTP session).