Java UnsupportedOperationException — What It Means & How to Fix It

What Does This Error Mean?

An UnsupportedOperationException means you tried to do something that the object does not support — usually trying to add, remove, or change items in a collection that is fixed or read-only. The most common cause is creating a list with Arrays.asList() or List.of() and then trying to modify it. These methods return fixed-size or immutable lists that look like regular lists but cannot be changed.

Affected Models

Java 8
Java 11
Java 17
Java 21
All Java versions

Common Causes

Calling add() or remove() on a list created with Arrays.asList() — it is fixed-size and cannot grow or shrink
Calling any mutating method on a list created with List.of() or List.copyOf() — these are fully immutable
Using Collections.unmodifiableList() to wrap a list and then trying to modify the wrapper
Implementing an interface where an optional method is not supported, and that method is called
Calling set() on an iterator from a collection type that does not support element replacement

How to Fix It

Identify where the collection was created. If it was created with Arrays.asList(), List.of(), Map.of(), or wrapped with Collections.unmodifiableList(), it cannot be modified directly.

These are intentionally immutable or fixed-size. They are not bugs in Java — they are features for safe read-only data sharing.
If you need a modifiable copy, wrap it in a new ArrayList: new ArrayList<>(Arrays.asList(...)) or new ArrayList<>(List.of(...)). This creates a mutable copy you can freely add to or remove from.

Example: List<String> mutable = new ArrayList<>(List.of('a', 'b', 'c')); — now you can call add() and remove() safely.
For Maps, use new HashMap<>(Map.of(...)) to get a mutable map from an immutable one. The same principle applies — copy it into a mutable type.

new LinkedHashMap<>() preserves insertion order if that matters. new TreeMap<>() sorts by key.
If you need the collection to remain immutable but the operation seems necessary, reconsider your design. You may need to create a new collection rather than modifying the existing one.

This is the immutable data pattern — instead of changing an existing collection, create a new one with the changes applied. It is safer in multi-threaded code.
When implementing an interface with optional operations (like the Iterator's set() or add() methods), either implement all operations or clearly document which ones are not supported and why.

If you throw UnsupportedOperationException intentionally in your own code, always include a helpful message: throw new UnsupportedOperationException('This list is read-only');

When to Call a Professional

UnsupportedOperationException is always a fixable code issue. The stack trace points to the method you called that is not supported. The fix is almost always to copy the collection into a mutable ArrayList before trying to modify it.

Frequently Asked Questions

Why does Arrays.asList() return a list that cannot be modified?

Arrays.asList() returns a fixed-size list backed by the original array. You can change existing elements with set(), but you cannot add or remove elements because the underlying array cannot resize. If you need full mutability, copy it: new ArrayList<>(Arrays.asList(...)).

What is the difference between Arrays.asList() and List.of()?

Arrays.asList() returns a fixed-size list — you can change elements but not add/remove. List.of() (Java 9+) returns a fully immutable list — you cannot change, add, or remove anything. List.of() also rejects null elements, while Arrays.asList() allows them.

Is UnsupportedOperationException checked or unchecked?

It is unchecked — it extends RuntimeException. This means you do not need to declare or catch it. It surfaces at runtime when you call an operation that the collection type does not support. The only fix is to use a collection type that supports the operation you need.