Java Object Deserialization: How It Works and How to Do It Safely
How Java object deserialization works, why deserializing untrusted data is dangerous, and practical protections including serialization filters, validation, and safer formats.

Java object deserialization is the process of reconstructing an object from its serialized byte stream. While the mechanism is straightforward, it carries a well-known security risk: deserializing untrusted data can lead to remote code execution. This article explains the mechanics, the dangers, and the practical steps you can take to deserialize safely.
How Java Object Deserialization Works
Java's native serialization mechanism converts an object's state into a byte stream using ObjectOutputStream. The reverse operation, deserialization, reads that byte stream and rebuilds the object graph using ObjectInputStream. The readObject() method is the entry point. When called, the JVM reads the class metadata, field values, and references from the stream, then reconstructs the object graph. For a serializable class, the normal constructor is not invoked during this process, so initialization logic in that constructor is bypassed. Depending on the class hierarchy, the first non-serializable superclass may still have its no-arg constructor invoked by the serialization machinery.
The process is recursive. If the serialized object contains references to other objects, those are also deserialized automatically. This can lead to a deep object graph, and the total amount of memory and CPU consumed depends on the size and complexity of the stream. Because the format is binary and includes class metadata, the stream is not human-readable and cannot be easily validated by simple string checks.
Implementing Deserialization with ObjectInputStream
The most basic way to deserialize an object is to wrap an InputStream with ObjectInputStream and call readObject(). Here is a minimal example:
import java.io.*;
public class DeserializeExample {
public static Object deserialize(byte[] data) throws IOException, ClassNotFoundException {
try (ObjectInputStream ois = new ObjectInputStream(new ByteArrayInputStream(data))) {
return ois.readObject();
}
}
}This method reads a single object from the byte array. The return type is Object, so the caller must cast it to the expected type. The cast can fail at runtime if the actual class in the stream is not assignable to the target type, which is one reason deserialization is inherently unsafe when the input is not trusted.
A common pattern is to deserialize a specific type, such as a User object:
User user = (User) deserialize(data);This works only if the User class implements Serializable and has a matching serialVersionUID. During deserialization, the JVM compares the stream's serialVersionUID with the local class's serialVersionUID. If the class does not explicitly declare one, the JVM derives it from the class structure, so changes to the class can cause an InvalidClassException even when the change seems compatible. This compatibility check is a source of operational headaches, especially in distributed systems where producers and consumers may be upgraded independently.
Why Native Deserialization Is a Security Risk
The core problem is that readObject() can cause the JVM to load classes named in the stream as long as they are on the classpath. An attacker who controls the byte stream can craft a sequence of class names and field values that, when deserialized, can trigger arbitrary code execution if a suitable chain of gadget classes is available. This is known as a deserialization gadget chain. Libraries such as Apache Commons Collections, Spring, and Groovy have historically contained gadgets that can be chained to call dangerous methods like Runtime.exec().
Even without a full gadget chain, deserialization can cause denial-of-service attacks. A malicious stream can declare an array of enormous size or a deeply nested object graph, forcing the JVM to allocate excessive memory or perform recursive operations until it crashes. Because there is no built-in limit on the number of objects or the depth of the graph, a tiny payload can consume gigabytes of memory.
The risk is not theoretical. Many high-profile vulnerabilities, including several CVEs in Java frameworks, have been caused by unsafe deserialization of untrusted input. The Java community has responded with multiple defense mechanisms, but the safest approach is to avoid native deserialization altogether when the data comes from an untrusted source.
Validating Input Before Deserialization
If you must deserialize data that might be untrusted, you should validate it before calling readObject(). The first line of defense is to ensure the byte stream conforms to an expected structure. For example, you can check the magic header bytes (the stream starts with 0xAC 0xED) and the version number, but this is a weak check because an attacker can easily replicate those bytes.
A more effective validation is to inspect the class names that are being deserialized. You can override the resolveClass() method in a custom ObjectInputStream subclass to enforce an allowlist of permitted classes. Here is an example:
public class SafeObjectInputStream extends ObjectInputStream {
private static final Set<String> ALLOWED_CLASSES = Set.of(
"com.example.User",
"java.util.ArrayList"
);
public SafeObjectInputStream(InputStream in) throws IOException {
super(in);
}
@Override
protected Class<?> resolveClass(ObjectStreamClass desc) throws IOException, ClassNotFoundException {
if (!ALLOWED_CLASSES.contains(desc.getName())) {
throw new InvalidClassException("Unexpected class", desc.getName());
}
return super.resolveClass(desc);
}
}This approach blocks unknown classes before they are loaded, but it is not sufficient by itself. An allowed class might still contain dangerous methods that can be triggered through its fields. The allowlist must be carefully curated to include only classes that are known to be safe and that do not have gadget potential.
Using Serialization Filters to Restrict Types
Java 9 introduced a built-in serialization filter mechanism that provides a more robust way to control what can be deserialized. You can configure a filter globally via the system property jdk.serialFilter, or programmatically on a specific ObjectInputStream using setObjectInputFilter(). A filter can restrict class names and enforce limits on array sizes, graph depth, and total stream length.
Here is an example of setting a filter programmatically:
ObjectInputFilter filter = ObjectInputFilter.Config.createFilter(
"com.example.*;java.util.*;!*;maxdepth=10;maxarray=1000;maxbytes=100000"
);
ObjectInputStream ois = new ObjectInputStream(new ByteArrayInputStream(data));
ois.setObjectInputFilter(filter);The filter pattern syntax lets you list class name patterns, each optionally prefixed with ! to reject it, plus limits such as maxdepth, maxarray, and maxbytes. The first pattern that matches a resolved class determines whether that class is allowed or rejected. If no pattern matches, the status is UNDECIDED; that does not automatically block the class, so include a final catch-all rule such as !* if you want to reject classes that are not explicitly allowed.
Serialization filters are a significant improvement over manual resolveClass() overrides because they are integrated into the JVM and can be applied consistently across all deserialization points. However, they are not a silver bullet. A filter that is too permissive may still allow a gadget chain, while a filter that is too restrictive may break legitimate functionality. You must test your filter against the actual classes your application uses.
Alternatives to Native Deserialization
Given the risks, many applications have moved away from Java's native serialization for data exchange. Instead, they use text-based or structured formats like JSON, XML, or Protocol Buffers. These formats are human-readable (in the case of JSON and XML) and have well-defined parsing rules that do not automatically instantiate arbitrary classes.
For example, using Jackson to deserialize JSON is safer because the parser only creates instances of the target class and its properties, not arbitrary classes from the input. You still need to configure Jackson to reject unknown properties and to avoid polymorphic typing unless absolutely necessary. Here is a simple example:
ObjectMapper mapper = new ObjectMapper();
User user = mapper.readValue(json, User.class);This approach is not only safer but also more portable across languages and platforms. JSON and Protocol Buffers are language-agnostic, so a Java service can communicate with a Python or Go service without dealing with Java's serialization format. The tradeoffs vary by format: text formats such as JSON and XML are usually bulkier than compact binary formats, Protocol Buffers require explicit schema management, and each format needs explicit mapping to Java objects.
When Native Deserialization Is Still the Right Choice
There are a few scenarios where native Java object deserialization remains a reasonable choice. The most common is when you are deserializing data that was produced by your own application and stored in a controlled environment, such as a local cache or a database column. If the data never leaves the trust boundary, the risk is minimal. For example, you might serialize a session object and store it in memory or on disk, then deserialize it later in the same JVM.
Another case is when you are using a framework that already handles deserialization safely, such as a library that applies its own filters. But even then, you should not assume safety without verifying the configuration. The safest policy is to treat any data that crosses a network boundary as untrusted and to use a non-native format.
If you must use native deserialization, combine multiple defenses: use a strict serialization filter, validate the input size, and keep your dependencies updated to avoid known gadget chains. Also, consider using a custom ObjectInputStream that rejects classes outside a small allowlist. No single measure is foolproof, but layering them reduces the attack surface significantly.
Finally, remember that deserialization is not just a security concern; it also affects performance. Native deserialization is CPU-intensive and allocates many objects, especially for large object graphs. If your application deserializes high-volume data, a structured format like JSON with a streaming parser may offer better throughput and lower memory overhead. Measure your actual workload before choosing a format, and always test with realistic data sizes.
Try matching browser tools
All toolsSmall utilities that fit Java work — they run entirely in this browser tab, so nothing you paste leaves your device.
Related Java guides
All Java guidesJava Final Keyword: Usage and Behavior
How Java's final keyword works for variables, methods, and classes, with practical examples and decision guidance for using it.
Java Final Variable: Syntax, Behavior, and Use Cases
Understand what a final variable in Java means, how initialization works, and when to use it for constants, immutability, and clearer code.
Java Duration vs Period: When to Use Each
java duration vs period: Compare Java Duration and Period to handle time-based and date-based calculations correctly. Learn syntax, conversion, and pitfalls.
Instance vs Static Variables in Java: Key Differences
Understand the difference between instance and static variables in Java, including memory, lifecycle, and when to use each.
More in Java
All Java guidesThe guides filed next to this one in Java, in library order.