Java Reference ยท java.lang
ClassCastException
Reference for ClassCastException: why bad reference casts fail at run time, heap pollution with generics, and how instanceof pattern matching prevents it.
ClassCastException is thrown when you cast a reference to a type that the object is not actually an instance of. The compiler allows the cast when it is possible (the types are related), and the JVM checks it at run time. It extends RuntimeException.
Upcasts never fail, and a cast to the object's real type or one of its supertypes succeeds. Casting an Object that holds a String to Integer fails. Casts between unrelated classes (such as String to Integer directly) are rejected by the compiler instead.
Object value = "text"; Integer number = (Integer) value; // ClassCastException at run time
Try it
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.
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
public class ClassCastException extends RuntimeException
| Constructor | Description |
|---|---|
ClassCastException() |
No message. |
ClassCastException(String message) |
Detail message. |
The JVM-generated message names both types, for example class Main$Cat cannot be cast to class Main$Dog, followed by details about class loaders and modules.
Usage notes
- The compile-time rule: a cast between two classes compiles only if one is a subtype of the other (interfaces are more permissive). The run-time rule: the object's actual class must be the target type or a subtype.
- Primitives do not use this. Narrowing primitive casts (
(int) 3.9) never throw; they truncate. Casting a boxed value, as in(int) someObject, first needs the object to be anInteger. - Test with
instanceof(with pattern matching, Java 16+) or aswitchwith type patterns (Java 21+), which bind a correctly typed variable and avoid the cast completely. - Generics and erasure.
(List<String>) objis an unchecked cast: the JVM only checksList. Elements fail later with aClassCastExceptionat a place that has no cast in your source. Avoid raw types and keep unchecked warnings to a minimum. - Heterogeneous data (JSON,
Object[], legacy APIs) is the usual source. Convert at the boundary into a typed object and validate there. - Wrapper types differ. An
Integercannot be cast toLongorDouble, even though the primitives convert. UseNumber.longValue()instead. - Class loaders. Two classes with the same name loaded by different loaders are different types, a puzzling cause in application servers.
- Prefer polymorphism (a method on the supertype) over casting down to call subtype methods.