Java Record Immutability: Guarantees and Limitations
Java records guarantee immutability for their own fields, but mutable components need extra care. Learn what the compiler enforces, where records are only shallowly immutable, and how to handle validation, defensive copying, and serialization.

When you declare a Java record, the compiler generates a final class with private final fields, a canonical constructor, accessor methods, equals, hashCode, and toString. The immutability of records is a central design goal, but it is important to understand exactly what that immutability means in practice. Records enforce immutability at the language level for the fields you declare, yet they do not automatically make every object graph deeply immutable.
What the Compiler Enforces
A record declaration like this:
public record Point(int x, int y) {}produces a class with two private final fields, x and y. The canonical constructor assigns these fields exactly once. There are no setters, and the accessor methods x() and y() simply return the field values. Because the fields are final and the class is final, no subclass can add mutable state or override the accessors to return something different. The compiler also generates equals, hashCode, and toString based on the component values, which are consistent with the immutable state.
This means that once a record instance is created, its component values cannot be reassigned. You cannot change point.x or point.y after construction. Under normal use, this is a stronger guarantee than a typical mutable class with getters and setters. It is not an absolute security boundary: reflective code can sometimes bypass final if the module and security configuration allow it.
Where Immutability Ends: Mutable Components
The guarantee applies to the references stored in the record's fields, not to the objects those references point to. If a record component is an array, a List, a Map, or any other mutable object, the record itself is only shallowly immutable. For example:
public record Names(List<String> names) {}The names field is final, but the List instance it references can be modified after the record is created. Callers who obtain the list through names() can add or remove elements. This is a common source of confusion because the record's immutability is often mistaken for deep immutability.
To protect against this, you need to make defensive copies in the constructor and in the accessor. The canonical constructor can copy the incoming list, and the accessor can return an unmodifiable view. However, this is manual work and is not automatically generated by the record syntax.
Defensive Copying in Records
Consider a record that should hold a list of tags:
public record TaggedItem(String id, List<String> tags) {
public TaggedItem {
tags = List.copyOf(tags);
}
@Override
public List<String> tags() {
return List.copyOf(tags);
}
}The compact constructor reassigns the tags parameter to an unmodifiable list. The accessor also returns an unmodifiable list built from the current contents each time it is called. This ensures that the caller cannot modify the record's internal state through the returned list. It may allocate a new list on each access, which can be acceptable for small collections but could be a performance concern for large ones.
An alternative is to store an immutable list type, such as List.copyOf or an unmodifiable list, and return it directly if you are certain the caller will not attempt to modify it. But returning the internal reference still exposes the object; if it is truly immutable, that is safe. The key is to decide whether the component type is itself immutable.
Arrays and Records
Arrays are inherently mutable, even if the reference is final. A record with an array component is problematic because the array elements can be changed. For example:
public record Matrix(int[][] values) {}Here, values is a final reference to an array, but the inner arrays and the elements can be modified. To make this record truly immutable, you would need to deep-copy the entire array structure in the constructor and accessors, which is tedious and error-prone. In practice, it is often better to use immutable collection types or to avoid exposing arrays directly.
If you must use an array, consider storing a clone and returning a clone from the accessor. But be aware that this only provides a shallow copy for multi-dimensional arrays. Deep immutability requires recursive copying.
Validation in the Canonical Constructor
The canonical constructor is the only place where you can validate the state of a record before it is created. Because the fields are final, you cannot validate later. This is a natural fit for enforcing invariants. For example:
public record Temperature(double celsius) {
public Temperature {
if (celsius < -273.15) {
throw new IllegalArgumentException("Temperature below absolute zero");
}
}
}The compact constructor syntax allows you to add validation without explicitly declaring the parameter list. The compiler implicitly assigns the validated values to the fields. This keeps the validation logic in one place and prevents invalid instances from ever existing.
Records vs Traditional Immutable Classes
Before records, you would write an immutable class manually with private final fields, a constructor, getters, and overridden equals, hashCode, and toString. Records reduce that boilerplate and make the intent explicit. However, traditional immutable classes give you more flexibility. You can hide the constructor behind a factory method, cache instances, or perform complex initialization. Records have a fixed constructor signature and no inheritance, which can be limiting.
For simple data carriers, records are usually the better choice. For objects with complex behavior or that need to participate in an inheritance hierarchy, a traditional class may be more appropriate. The decision should be based on whether the record's constraints align with your design.
Serialization and Reflection
Records interact with Java serialization in a specific way. When a record is serialized and deserialized, the canonical constructor is invoked for deserialization. This means validation in the constructor is preserved during deserialization. This is a significant advantage over traditional classes where serialization can bypass constructor checks.
Reflection can read record components through the accessors and through the Record component API, but setting the underlying fields is not part of the record contract. The fields are declared final, and reflective modification is not an intended path. In a Java Platform Module System (JPMS) setup, it is blocked unless the caller is in the same module or the package is opened to the caller; in less restricted configurations, reflection may still be able to alter final fields. Do not treat records as a security boundary.
Performance and Memory Considerations
The main runtime costs to consider are the generated equals, hashCode, and toString implementations, which operate on all components. For large or expensive components, these generated methods may be costlier than a custom implementation. The more common cost in practice is defensive copying: if you copy collections in the constructor and accessor, you add allocation overhead. For read-mostly scenarios, this may be negligible. For high-throughput code, consider using immutable collection types like List.of and Map.of, which are already immutable and can be returned directly without copying.
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.