Skip to content
Tutorials Center
My learning

Topics

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.

Java
Object value = "text";
Integer number = (Integer) value;   // ClassCastException at run time

Try it

Java A failing cast and its message

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 Generics and heap pollution

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 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 an Integer.
  • Test with instanceof (with pattern matching, Java 16+) or a switch with type patterns (Java 21+), which bind a correctly typed variable and avoid the cast completely.
  • Generics and erasure. (List<String>) obj is an unchecked cast: the JVM only checks List. Elements fail later with a ClassCastException at 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 Integer cannot be cast to Long or Double, even though the primitives convert. Use Number.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.