Java UnsupportedOperationException: Causes and How to Fix

java.lang.UnsupportedOperationException is an unchecked exception that a method throws when its object does not support the requested operation, and in most cases it means our code tried to add, remove or replace elements in a collection that cannot be changed. The fix is to copy the data into a mutable collection, such as new ArrayList<>(list) or new HashMap<>(map), before changing it.

The exception comes up in these common cases.

• Arrays.asList() returns a fixed-size list, so add() and remove() throw, while set() works.
• List.of(), Set.of(), Map.of() and Stream.toList() return unmodifiable collections, so every change throws.
• Collections.unmodifiableList() and Collections.unmodifiableMap() return read-only views, so add(), put() and remove() throw.
• The keySet() and values() views of a Map support removing entries but throw on add().
• A class does not implement an optional method and contains throw new UnsupportedOperationException() in it, as many interface default methods and stubs do.

The following example triggers the exception in the three most common cases, and fixes each one with a mutable copy (Java 25).

// 1. Causes
List<String> fixed = Arrays.asList("a", "b", "c");
boolean added = fixed.add("d");                     // UnsupportedOperationException

List<String> immutable = List.of("a", "b");
boolean removed = immutable.remove("a");            // UnsupportedOperationException

Map<String, Integer> view = Collections.unmodifiableMap(new HashMap<>(Map.of("apple", 5)));
Integer gone = view.remove("apple");                // UnsupportedOperationException

// 2. Fix: copy into a mutable collection
List<String> mutable = new ArrayList<>(fixed);
boolean ok = mutable.add("d");                      // true, mutable = [a, b, c, d]

Map<String, Integer> prices = new HashMap<>(view);
Integer price = prices.remove("apple");             // 5, prices = {}

Notice that the first at line of the stack trace names the collection type, such as java.util.AbstractList.add for Arrays.asList(), java.util.ImmutableCollections.uoe for List.of() and Stream.toList(), and java.util.Collections$UnmodifiableMap.remove for the unmodifiable wrapper. That line tells us which kind of read-only collection the code tried to change.

In the next sections, we look at the class itself and the Arrays.asList() case with its full stack trace, and then fix it with ArrayList.

1. Root Cause of UnsupportedOperationException

The UnsupportedOperationException class is a member of the Java Collections Framework since Java version 1.2. It extends RuntimeException, so it is an unchecked exception and need not be declared in a method’s or a constructor’s throws clause.

public class UnsupportedOperationException extends RuntimeException

As the name implies, UnsupportedOperationException occurs when a requested operation is not supported in a class or interface. It is a common exception that occurs while working with collections such as List, Queue, Set and Map. For example, if we try to modify an unmodifiable Map or List, this exception is thrown.

One of the most common occurrences is while using the Arrays.asList() method. Since the asList() method returns a fixed-size List backed by the array, the add() and remove() methods are not supported, and calling them throws UnsupportedOperationException. The set() method still works, because it does not change the size of the list.

List<String> list = Arrays.asList(new String[] { "a", "b", "c" });

list.add("d");
//or 
list.remove("a");

We will get the UnsupportedOperationException in the console.

Exception in thread "main" java.lang.UnsupportedOperationException
	at java.base/java.util.AbstractList.add(AbstractList.java:155)
	at java.base/java.util.AbstractList.add(AbstractList.java:113)
	at UnsupportedOperationExceptionExample.main(UnsupportedOperationExceptionExample.java:8)

2. Resolving UnsupportedOperationException

The UnsupportedOperationException can be resolved by using a mutable collection, such as ArrayList. If we have unmodifiable collections, we can copy them into a mutable collection class.

For example, the fixed-size List in the earlier example can be passed to a new ArrayList object, which is a mutable collection.

Java Arrays.asList() vs new ArrayList()

List<String> list = Arrays.asList(new String[] { "a", "b", "c" });

List<String> arraylist = new ArrayList<>(list);

//Works fine
arraylist.add("d");   
arraylist.remove("a");

Here, a new ArrayList object is created using the fixed-size list returned from the Arrays.asList() method. When a new element is added to the ArrayList, it works as expected and resolves the UnsupportedOperationException.

The copy is independent of the original, so changes to arraylist do not show up in list. For a Map, new HashMap<>(map) works the same way, and for a Set, we use new HashSet<>(set).

3. Conclusion

In this article, we learned about UnsupportedOperationException, what causes it and how to prevent it in our code.

The exception almost always points to a collection that is fixed-size or unmodifiable, created by Arrays.asList(), List.of(), Stream.toList() or a Collections.unmodifiable method. Copying the data into an ArrayList, HashMap or HashSet before modifying it removes the exception.

4. References

• UnsupportedOperationException Javadoc (Java 25)
• Unmodifiable Lists in the List Javadoc (Java 25)
• Arrays.asList() Javadoc (Java 25))

Happy Learning !!