Skip to content
Tutorials Center
My learning

Topics

Java Reference ยท java.lang

The UnsupportedOperationException class

Reference for UnsupportedOperationException: why List.of(), Arrays.asList() and unmodifiable views throw it, and how to make mutable copies.

java.lang.UnsupportedOperationException is an unchecked exception that an object throws to say "this operation is not available on me". It is most often seen when you try to modify a collection that is immutable or only partly modifiable: List.of(1, 2).add(3) fails, as does add on an unmodifiable view.

The exception is part of the design of the collections framework: many mutating methods are documented as optional operations, and implementations that cannot support them throw this exception instead of silently ignoring the call. You can also throw it yourself in your own classes, for example when a method of an interface does not make sense for one implementation.

Java
public class UnsupportedOperationException extends RuntimeException

Try it

Java Collections that refuse changes

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Java Making mutable copies and throwing it yourself

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with IO.readln() or a Scanner), it gets the next line from this box.

Syntax

Java
public UnsupportedOperationException()
public UnsupportedOperationException(String message)
public UnsupportedOperationException(String message, Throwable cause)
public UnsupportedOperationException(Throwable cause)
Constructor Description
() No message. This is what the immutable collections throw, so getMessage() is null.
(String message) A message for the caller.
(String message, Throwable cause) Message plus the underlying cause.
(Throwable cause) Wraps a cause; the message becomes cause.toString().

Usage notes

  • Immutable collections from List.of, Set.of, Map.of, List.copyOf, Stream.toList() (Java 16+) and Collectors.toUnmodifiableList() throw on every mutator, even when the call would change nothing (for example clear() on an empty List.of()).
  • Arrays.asList(...) returns a fixed-size list backed by the array: set and sort work and write through to the array, while add and remove throw.
  • Collections.unmodifiableList(...) is a read-only view, not a copy. Changes to the underlying list still show through it. Use List.copyOf() for a real snapshot.
  • Fix: copy into a mutable collection (new ArrayList<>(other)) before changing it, or choose the right collection from the start.
  • Iterator.remove() is optional too and throws this exception for iterators that do not support it.
  • Do not catch it to probe capabilities. Decide at design time which collection you hold. In your own APIs, prefer splitting interfaces over throwing from default methods when an operation is unsupported for most implementers.
  • Documentation matters. If a method may throw this exception, say so in your Javadoc, because the compiler will not force callers to handle it.