Fix UnsupportedOperationException on Immutable Lists
Why List.of, Arrays.asList and Stream.toList reject changes with UnsupportedOperationException, and how to get a list you can modify.

You called add on a list and got an exception with no message:
List<String> tags = List.of("java", "spring");
tags.add("hibernate");Exception in thread "main" java.lang.UnsupportedOperationException
at java.base/java.util.ImmutableCollections.uoe(ImmutableCollections.java:142)The list was immutable on purpose. The exception is the contract, and the stack trace even names ImmutableCollections. The question is which factory gave you the list and what to do instead. The language-level view is in the modern Java guide.
Which methods return which kind of list
| Source | add / remove | set | Notes |
|---|---|---|---|
List.of(...) | throws | throws | Immutable, rejects null elements |
Stream.toList() | throws | throws | Immutable, allows null |
Collectors.toList() | works in practice | works | No guarantee in the specification |
Arrays.asList(array) | throws | works | Fixed-size view backed by the array |
Collections.unmodifiableList(l) | throws | throws | Read-only view of another list |
new ArrayList<>(...) | works | works | An ordinary modifiable list |
Collectors.toList() returns an ArrayList today, and the documentation promises nothing, so code that relies on that is fragile. If a method returns Collectors.toList() in one version of a library and Stream.toList() in the next, callers that mutate the result start throwing.
Fix: make a copy you own
List<String> tags = new ArrayList<>(List.of("java", "spring"));
tags.add("hibernate");The copy constructor takes the elements and gives you a mutable list. This is also how to defend against a caller who passes you an immutable list you need to change, and how to hand out data without letting others change your internal list: return List.copyOf(internal).
Arrays.asList is a special case
List<String> days = Arrays.asList("mon", "tue");
days.set(0, "sun"); // works, and writes through to the array
days.add("wed"); // UnsupportedOperationExceptionThe list is a window onto the array, and an array cannot grow. Wrap it with new ArrayList<>(Arrays.asList(...)) if you want to add, or use List.of if you want it fixed.
The view trap
List<String> source = new ArrayList<>(List.of("a", "b"));
List<String> readOnly = Collections.unmodifiableList(source);
source.add("c");
System.out.println(readOnly); // [a, b, c]unmodifiableList blocks changes through the wrapper, not through the original. If you want a snapshot nobody can change, use List.copyOf(source).
The same rules for sets and maps
Set.of, Map.of, Map.ofEntries and Map.copyOf are immutable. They also reject duplicate elements or keys at creation with IllegalArgumentException, and reject null. If a Map.of call throws NullPointerException, a value or key was null.
In frameworks
A Spring @ConfigurationProperties list or a JPA collection may be unmodifiable or a Hibernate wrapper that throws on certain operations. A repository method that returns List from a Stream.toList() is immutable. If the exception appears after you changed a collection type or upgraded a library, check the source of the list.
Which factory gives which behaviour
The exception message is null in every case, so it never says which list you hold. This program tries to modify lists from the common factories and prints what happens. It ran on Eclipse Temurin 25.0.5.
tryAdd("List.of", List.of("a", "b"));
tryAdd("Arrays.asList", Arrays.asList("a", "b"));
tryAdd("stream.toList()", Stream.of("a", "b").toList());
tryAdd("Collectors.toList", Stream.of("a", "b").collect(Collectors.toList()));
tryAdd("Collections.unmodifiableList", Collections.unmodifiableList(new ArrayList<>(List.of("a"))));List.of: UnsupportedOperationException message=null
Arrays.asList: UnsupportedOperationException message=null
stream.toList(): UnsupportedOperationException message=null
Collectors.toList: added, size 3
Collections.unmodifiableList: UnsupportedOperationException message=nullOnly Collectors.toList() returned a list you may add to, and even that is only an implementation detail the documentation does not promise. Stream.toList(), added in JDK 16, returns an unmodifiable list, and code that replaced collect(Collectors.toList()) with it during a modernisation is a typical source of this exception months later. If a caller will modify the result, say so in the method contract and return a new ArrayList.
Modifying vs replacing in Arrays.asList
Arrays.asList is the odd one. It is fixed-size but writable: you can replace elements, and the changes write through to the array, yet you cannot add or remove.
Arrays.asList: set ok -> [z, b]
List.of.set: UnsupportedOperationExceptionThat is why the same call sequence can pass a test with one factory and fail with another. A method that sorts its input in place works on Arrays.asList (it only sets elements) and fails on List.of. The error is in the method that mutates a list it was handed.
Unmodifiable is not the same as immutable
Collections.unmodifiableList returns a read-only view of another list. Changes to the original appear in the view, which defeats a defensive copy. List.copyOf takes a snapshot.
view reflects the source: [a, b, c]
List.copyOf is a snapshot : [a, b, c]The view showed c after the original gained it. The copy was taken after c and before d, and stayed at [a, b, c] when d was added later. For a class that exposes a collection from its state, return List.copyOf(items) or an unmodifiable view, and decide which on purpose: the copy is safe against later changes and costs a copy on each call, the view is free and moves with the source. Also remember that List.of rejects null elements with a NullPointerException, which is the other surprise the run confirmed.
Fix it where the mutation happens
Three fixes cover almost every case, in order of preference. Change the code that mutates to work on a copy it owns, so the contract of the method does not depend on what its caller passes.
public List<String> sortedNames(List<String> input) {
List<String> copy = new ArrayList<>(input); // a list we own
Collections.sort(copy);
return copy;
}Or use a method that does not mutate: input.stream().sorted().toList(). Or, when the caller really owns the list and the method is meant to mutate it, document that and make the caller pass an ArrayList. Resist catching UnsupportedOperationException to fall back to a copy, which hides the contract problem and makes behaviour depend on the argument type.
In frameworks
Spring, Hibernate and Jackson all return unmodifiable collections in places. Spring's Environment and request parameter maps are read-only. Hibernate hands back its own PersistentBag, which is modifiable, but List.of assigned to an entity's collection field can break Hibernate's change tracking, so initialise entity collections with new ArrayList<>(). Jackson deserialises into ArrayList by default and into an immutable list only for types you declare as such. When the stack trace shows the exception thrown from inside a library, read upward to the first frame of your code: that is the method holding the wrong list.
Stop copying between collections by accident
Defensive copies fix mutation bugs and cost allocation, so make them on boundaries, not everywhere. Copy when a mutable list enters your class from outside and you will hold it, and copy when a mutable field leaves it. Inside a class, pass collections by reference and treat them as read-only by convention. A record with a list component is a good example of where to copy once:
record Order(String id, List<String> lines) {
Order {
lines = List.copyOf(lines); // snapshot at construction; also rejects null elements
}
}The compact constructor makes the record deeply immutable with respect to its list. Callers that pass an ArrayList and keep modifying it do not affect the order, and callers that try order.lines().add("x") get the exception this post is about, at the point of the mistake and with a stack trace that names their line, not a library's.
Where this does not apply
If you wanted to modify a list while looping over it and got ConcurrentModificationException, the list is mutable and the loop is wrong: see that fix. Prefer immutable collections for data that crosses a method boundary: they cannot be corrupted by a caller. Another runtime exception that follows from wrong assumptions about collections is ClassCastException from heap pollution. The [List interface documentation](https://docs.oracle.com/en/java/javase/25/docs/api/java.base/java/util/List.html) lists the immutable factories, and the Collections Framework overview explains the unmodifiable wrappers.


