readResolve

How readResolve works in Java serialization

readResolve is invoked after an object has been deserialised, but before the final reference is returned to caller code. It lets the class substitute a different object, which is why it is often used for singletons, canonical value objects, and proxy patterns where the stream representation should not become the runtime identity.

That substitution step is the important design point: the stream can contain a valid serialized instance, while the application intentionally receives a different canonical object. In practice, this means the method can preserve invariants that ordinary deserialization would otherwise break.

Why readResolve exists

Without readResolve, deserialization creates a new object instance even when the program expects a single shared instance or a canonical representative. The hook gives the class control over object identity after reconstruction, which is especially useful when equality is not enough and reference identity matters.

It is also useful when the class wants to expose a proxy or wrapper in the stream, but return the underlying target object at runtime. That keeps the serialized form decoupled from the object the rest of the program should use.

Common patterns and correct use

The classic use case is a singleton: the serialized form may be recreated, but readResolve returns the one true instance instead of a duplicate. Another common pattern is value canonicalisation, where multiple serialized representations map back to a shared instance such as a cached constant, enum-like object, or interned value.

Because the hook runs during object reconstruction, it should be treated as part of the class's invariants, not as a convenience method. If the replacement object differs materially from the stream contents, the class must still ensure that callers cannot observe an inconsistent state between the raw deserialized object and the resolved one.

What can go wrong if it is misunderstood

readResolve does not make Java serialization safer by itself. It only changes the object returned after deserialization, so it cannot compensate for unsafe deserialization of hostile streams, broken class invariants, or logic that assumes the stream instance is the same object that application code will use.

It can also create subtle bugs if developers assume the deserialized instance's fields are what downstream code will see. If the replacement object has different state, or if a proxy is returned, code that relies on the pre-resolved instance can behave incorrectly during initialization, caching, or comparison.

Risk and Threat Considerations

When serialization is exposed to untrusted input, readResolve sits inside a broader deserialization risk surface, where attackers look for gadget chains, invariant bypasses, and unexpected object substitution. The method can help preserve intended object identity, but it can also conceal how much trust the application is placing in the incoming stream.

Failure mechanism: A crafted serialized payload may trigger class loading and object construction paths that execute before the resolved object is returned, so the security problem is often the deserialization process itself rather than the final replacement step.

Impact: The result can include logic abuse, state confusion, privilege-related bugs in application code, or exposure to deserialization vulnerabilities if the application accepts attacker-controlled streams.

Practitioner Guidance

Why practitioners should care: Use readResolve only when object identity or canonicalization is an explicit design requirement, because it changes what the caller receives and can hide a mismatch between the serialized form and the runtime object. Treat it as a correctness mechanism, not a security boundary.

What to watch for: Review any code path that deserializes external data, especially where singleton behavior, caches, or proxy objects are involved. If the class depends on readResolve, ensure that tests cover reference identity, state consistency, and the behavior of code that consumes the resolved object immediately after deserialization.