Java ClassCastException — What It Means & How to Fix It

What Does This Error Mean?

A ClassCastException means your code tried to treat an object as a type it is not. Imagine you have a box labelled 'Animal' and you assume it contains a Dog, but it actually contains a Cat. When you try to use Dog-specific features, Java throws ClassCastException because the Cat cannot pretend to be a Dog. This usually happens when working with collections, inheritance, or older Java APIs that do not use generics.

Affected Models

Java 8
Java 11
Java 17
Java 21
All Java versions

Common Causes

Casting an object to the wrong type — for example, casting a String to an Integer
Using raw (non-generic) collections like ArrayList without type parameters, then casting items on retrieval
A method returns an Object type and you assumed it would return a specific subclass, but it returned something different
Inheritance confusion — casting a parent class object to a child class when the actual object is a different child
Deserializing or unmarshalling data where the actual object type does not match the expected type

How to Fix It

Read the error message — it names both types. For example: 'class java.lang.String cannot be cast to class java.lang.Integer' tells you exactly what was attempted.

Go to the line in the stack trace and look at the cast on that line — the variable you are casting is not the type you think it is.
Use the instanceof operator to check the object's type before casting. This prevents the crash and lets you handle the unexpected type gracefully.

Example: if (myObject instanceof String) { String s = (String) myObject; } — this is safe because you check before casting.
Use generics on your collections. Declare List<String> instead of plain List. This moves the type check to compile time so the error is caught before the program even runs.

With List<String>, Java will not let you add a non-String item in the first place — no cast needed on retrieval.
In Java 16 and newer, use pattern matching with instanceof to combine the check and cast in one line: if (myObject instanceof String s) { ... use s ... }

This is cleaner and removes the repetition of having the type name twice — once in instanceof and once in the cast.
Trace back to where the object was created or returned. Confirm its actual type at the source. Add logging or use your debugger to print the object's actual class: myObject.getClass().getName().

This tells you the real type at runtime and helps you understand why it differs from what you expected.

When to Call a Professional

ClassCastException is always a code logic issue — no external help is needed. The error message tells you exactly which two types conflicted. The fix is either to use generics to prevent the problem, or to check the type before casting.

Frequently Asked Questions

How do generics prevent ClassCastException?

When you declare a collection like List<String>, Java enforces at compile time that only Strings can go in. When you take items out, Java knows they are Strings — no cast is needed. Without generics, everything is stored as Object, and you have to cast it yourself, which can fail at runtime.

Can ClassCastException happen with null?

No — casting null never throws ClassCastException. Null can be cast to any type without error. The exception only happens when you try to cast an actual object to an incompatible type.

What does 'unchecked cast' warning mean in my IDE?

It means you are casting to a generic type (like List<String>) without the compiler being able to verify it is safe. The warning is telling you this cast could fail at runtime. Use @SuppressWarnings('unchecked') only if you are certain the cast is safe and you understand why the warning appeared.