Java serialVersionUID: What It Is and When to Change It

The serialVersionUID is a private static final long field that holds the version number of a Serializable class, and Java compares it during deserialization to check that the class that wrote the bytes and the class that reads them are compatible. If the two numbers differ, readObject() throws an InvalidClassException instead of creating the object.

Java serialization converts an object into a stream of bytes, so we can store it on disk, keep it in a cache or send it over the network, and deserialization converts the bytes back. Between writing and reading, the class often changes, for example when a new release adds a field. The serialVersionUID decides whether those old bytes can still be read.

The following example declares the field in an Invoice class, the running example of this article.

class Invoice implements Serializable {

    @Serial
    private static final long serialVersionUID = 1L;   // version 1 of the serialized form

    private final String customer;
    private final int amount;

    Invoice(String customer, int amount) {
        this.customer = customer;
        this.amount = amount;
    }

    @Override
    public String toString() {
        return "Invoice[customer=" + customer + ", amount=" + amount + "]";
    }
}

Notice the three modifiers and the L suffix of the long literal. We cover the declaration rules, show a successful read, a version mismatch and a compatible change, look at how Java computes the value when we leave it out, and decide when to change it.

1. Java SerialVersionUID Syntax

A Serializable class declares its own serialVersionUID with a field that must be named serialVersionUID and be static, final and of type long. The Serializable Javadoc also advises the private modifier, because the field applies only to the class that declares it and is not useful to subclasses.

class Receipt implements Serializable {
    @Serial
    private static final long serialVersionUID = 1L;
}

A field with a different name, such as SerialVersionUID with a capital S, or with type int, is not the version field, and Java computes a default value instead. The @Serial annotation from Java 14 documents the intent, and javac -Xlint:serial warns with serializable class Receipt has no definition of serialVersionUID when the field is missing.

The value itself has no meaning beyond being equal or not equal. Many teams use 1L for the first version, and others paste the value generated by a tool, which we look at in section 3.

2. Java Serialization and Deserialization Examples

Each serialized object carries the class name and the serialVersionUID of its class in a class descriptor at the start of its data. When ObjectInputStream reads the object, it loads the local class with that name and compares the two numbers before it reads any field.

2.1. Same Version on Both Sides

The following example writes an Invoice to a file and reads it back with the same class. We also read the version number of the class with ObjectStreamClass.lookup(), which returns the declared value or the computed default.

Path file = Files.createTempFile("invoice", ".ser");
try (ObjectOutputStream out = new ObjectOutputStream(Files.newOutputStream(file))) {
    out.writeObject(new Invoice("Lokesh", 250));
}
Object restored;
try (ObjectInputStream in = new ObjectInputStream(Files.newInputStream(file))) {
    restored = in.readObject();
}
String text = restored.toString();                                        // "Invoice[customer=Lokesh, amount=250]"
long version = ObjectStreamClass.lookup(Invoice.class).getSerialVersionUID(); // 1

The read works because the stream and the local class both say version 1. During serialization, we handle IOException, and during deserialization also ClassNotFoundException, because the class must be on the classpath of the reading JVM.

2.2. Different Versions Throw InvalidClassException

To see a mismatch, we write the file with the class above and read it with a second build in which the line reads serialVersionUID = 2L. The second program fails on the first readObject() call.

java.io.InvalidClassException: com.howtodoinjava.core.serialization.Invoice; local class incompatible: stream classdesc serialVersionUID = 1, local class serialVersionUID = 2

The message names the class and both numbers, so the cause is clear from the log. A team uses the same mechanism on purpose, because changing the number is the way to make old data unreadable after an incompatible change.

2.3. A Compatible Change Keeps the Same Version

In the next build, we keep serialVersionUID = 1L and add a field String currency to Invoice. Adding a field is a compatible change, so the new class reads the old file, and the new field gets its default value because the stream has no data for it.

Invoice[customer=Lokesh, amount=250, currency=null]

Keep the serialVersionUID unchanged for compatible changes, and change it only when old data must be rejected. The full list of compatible and incompatible changes is in section 5.

3. How to Generate SerialVersionUID

If a serializable class does not declare a serialVersionUID, the serialization runtime computes one. It follows section 4.6 of the serialization specification, which builds a SHA-1 hash from these parts of the class and uses the first 8 bytes.

• The class name, the class modifiers and the names of the implemented interfaces.
• Every field except private static and private transient fields, with name, modifiers and type.
• Whether a static initializer exists.
• Every non-private constructor and method, with name, modifiers and parameter types.

So adding a public getter, renaming a method or adding an interface changes the computed value, even when the stored fields stay the same. The value can also differ between compilers, because compilers add synthetic members, for example for inner classes and assert statements. The specification therefore strongly recommends declaring the value in every serializable class.

We have four practical ways to get a value.

• Write 1L for a new class and increase it only for incompatible changes.
• Run the JDK tool serialver on the compiled class, which prints the computed value as a ready-to-paste declaration.
• Use the IDE quick fix, such as the IntelliJ IDEA inspection for a serializable class without serialVersionUID or the Eclipse warning, both of which can insert a generated value.
• Call ObjectStreamClass.lookup(type).getSerialVersionUID() in code, as in section 2.

$ serialver -classpath target/classes com.howtodoinjava.core.serialization.Invoice
com.howtodoinjava.core.serialization.Invoice:    private static final long serialVersionUID = 1L;

For a class with a declared field, serialver prints the declared value. For a class without one, it prints the computed hash, which is the number we need in the next section.

4. Java Classes without SerialVersionUID

A class without the field is not a situation we want to face, but it happens with older code. Say an app stores user sessions with Java serialization, and the session class has no serialVersionUID. A developer adds a small public helper method label() to the class, and after the next deployment, every stored session fails to load, although no field changed.

class Legacy implements Serializable {
    String code;
}

long computed = ObjectStreamClass.lookup(Legacy.class).getSerialVersionUID();  // a hash of the class structure

Reading a Legacy object written before the change gives this error, with the computed value of each version.

java.io.InvalidClassException: com.howtodoinjava.core.serialization.Legacy; local class incompatible: stream classdesc serialVersionUID = -6572036464690860334, local class serialVersionUID = 4888584158299352410

The fix is to run serialver on the old class, which is the build that wrote the data, and declare that value in the new class. The value from the stream is also printed in the exception message, as stream classdesc serialVersionUID, so we can take it from there when the old build is gone.

$ serialver -classpath old-build/classes com.howtodoinjava.core.serialization.Legacy
com.howtodoinjava.core.serialization.Legacy:    private static final long serialVersionUID = -6572036464690860334L;

With private static final long serialVersionUID = -6572036464690860334L; added to the new class, the old sessions load again, and the added method no longer matters. The default readObject() handles the compatible changes, so no custom code is needed. When a change is incompatible, such as a changed field type, we add a custom readObject() method that reads the old fields with readFields() and converts them.

5. When to Change the serialVersionUID

The versioning chapter of the specification lists which changes old streams survive. As long as the serialVersionUID stays the same, Java reads old data for every compatible change. For an incompatible change, the read either fails or produces wrong data, so we increase the number to make the failure explicit.

Compatible changes (keep the number)	Incompatible changes (change the number or handle them)
Adding fields	Deleting fields
Adding or removing writeObject() and readObject()	Changing the type of a primitive field
Changing the access modifier of a field	Changing a field to static or transient
Changing a field from static or transient to a normal field	Moving the class up or down the class hierarchy
Adding Serializable to a class	Switching between Serializable and Externalizable
Adding or removing a record component	Changing a class to an enum or back

Deleting a field is listed as incompatible because the older class version would get a default value. In practice, a newer class skips stream data that has no matching field, so a deletion with the same number only gives default values to older readers of newer data. For data that has to survive many releases, the Java serialization guide compares this approach with Externalizable and JSON.

6. Records, Enums and Arrays

Three kinds of types follow special rules, all defined in the serialization specification.

• A record has a default serialVersionUID of 0L, and the matching check is waived for records, because the runtime rebuilds a record from its components through the canonical constructor.
• An enum always has 0L, and a declared value is ignored, because only the constant name is serialized.
• An array class cannot declare the field, and the matching check is waived for arrays.

record Point(int x, int y) implements Serializable {}
enum Status { OPEN, PAID }

long recordUid = ObjectStreamClass.lookup(Point.class).getSerialVersionUID();  // 0
long enumUid = ObjectStreamClass.lookup(Status.class).getSerialVersionUID();    // 0

So records are a good choice for serializable data classes, because adding or removing a component does not break old streams and needs no serialVersionUID management.

7. serialVersionUID FAQs

A missing field and a field copied from another class are behind most of the questions about serialVersionUID.

7.1. What happens if we do not declare a serialVersionUID?

Java computes one from the class structure at runtime. Serialization works, but any change to the class signature, such as a new public method, changes the number, and old data fails with InvalidClassException. The compiler warns about the missing field only with -Xlint:serial, and IDEs show the same warning.

7.2. Is serialVersionUID inherited by subclasses?

No. Each serializable class in a hierarchy has its own version number, and the runtime checks the number of every class in the stream. A subclass without its own field gets a computed value, even when its superclass declares one, which is why the field is private.

7.3. Does every class need a unique serialVersionUID?

No. The number is compared only with other versions of the same class, so thousands of classes can all use 1L. Uniqueness across classes has no effect.

7.4. Is the serialVersionUID field itself serialized?

Not as object data, because it is a static field. The runtime writes its value into the class descriptor of the stream, once per class, which is how the reading side gets the number to compare. Other static fields are not written at all, so after deserialization they keep whatever value the class has in the reading JVM.

7.5. Does Jackson or Gson use serialVersionUID?

No. JSON libraries do not read it, because they map JSON properties to fields or constructor parameters by name. The field matters only for ObjectOutputStream and ObjectInputStream, including frameworks built on them, such as session replication in servlet containers or Java RMI.

8. Conclusion

The serialVersionUID is the version number of the serialized form of a class. Java compares the number in the stream with the number of the local class and throws InvalidClassException when they differ, before it reads any field.

We declare it as private static final long with @Serial in every serializable class, because the computed default changes with harmless edits such as a new method. We keep the number for compatible changes like added fields, change it for incompatible ones, and use serialver to rescue classes that never declared it. Records and enums need no number at all.

9. References

• Java Object Serialization Specification, Stream Unique Identifiers
• Java Object Serialization Specification, Versioning of Serializable Objects
• Serializable Javadoc
• InvalidClassException Javadoc
• The serialver Command

Happy Learning !!

Source Code on Github