IncompatibleClassChangeError in Java

1. Overview

In this article, we’ll explore the IncompatibleClassChangeError in Java, a runtime error that occurs when the JVM detects a class change that is incompatible with the previously loaded class.

We’ll delve into its causes with examples and effective strategies for resolving it.

2. The IncompatibleClassChangeError Class in Java

The IncompatibleClassChangeError is a type of linkage Error in Java. Linkage errors usually indicate an issue with one or many dependent classes.

IncompatibleClassChangeError is a subclass of LinkageError and is raised when there is an incompatible change to the class definition of one or more dependent classes.

It should be noted that this is a subclass of Error and hence we shouldn’t try to catch these errors as it signifies an abnormality in the application or runtime.

Let’s try to simulate an IncompatibleClassChangeError in a program to understand it better.

3. Generating the Error

Let’s try to emulate a scenario that causes the IncompatibleClassChangeError.

3.1. Preparing Libraries

We start by creating a simple library that has a parent class Dinosaur and a child class Coelophysis which extends the Dinosaur:

public class Dinosaur {
    public void species(String sp) {
        if(sp == null) {
            System.out.println("I am a generic Dinosaur");
        } else {
            System.out.println(sp);
        }
    }
}

public class Coelophysis extends Dinosaur {
    public void mySpecies() {
        species("My species is Coelophysis of the Triassic Period");
    }

    public static void main(String[] args) {
        Coelophysis coelophysis = new Coelophysis();
        coelophysis.mySpecies();
    }
}

We should notice that the species() method in the parent class is non-static.

3.2. Generating a JAR From the Library

Once this is done, we run the mvn package and generate a jar file from this project.

If we create an instance of the Coelophysis class and call the species() method, it would work correctly and generate the desired output:

➜ javac Coelophysis.java
➜ java Coelophysis
My species is Coelophysis of the Triassic Period

3.3. Creating a Second Version of the Library

Next, we create another library that is similar but has a slightly different version of the parent class Dinosaur including a static species() method:

public class Dinosaur {
    public Dinosaur() {
    }

    public static void species(String sp) {
        if (sp == null) {
            System.out.println("I am a generic Dinosaur");
        } else {
            System.out.println(sp);
        }
    }
}

We create a jar for this project as well and we import both of them into our client library using the Maven system import command:

<dependency>
    <groupId>org.dinosaur</groupId>
    <artifactId>dinosaur</artifactId>
    <version>2</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/src/main/java/com/baeldung/incompatibleclasschange/dinosaur-1.jar</systemPath>
</dependency>

3.4. Generating the Error

Now, when we call the Coelophysis class by passing the modified version as a classpath dependency, we get the error:

➜  java -cp dinosaur-2:dinosaur-1 Coelophysis
Exception in thread "main" java.lang.IncompatibleClassChangeError: Expecting non-static method 'void Dinosaur.species(java.lang.String)'
	at Coelophysis.mySpecies(Coelophysis.java:3)
	at Coelophysis.main(Coelophysis.java:8)

4. Common Causes of IncompatibleClassChangeError

IncompatibleClassChangeError in Java occurs when there is a binary incompatibility between classes, often caused by changes in the definition of a dependent class. Let’s walk through some common scenarios that might result in the error.

4.1. Changes to the Class Definition of a Dependent Class or Binary

Let’s consider a sub-class-parent class scenario and a change is done in some of the fields of the dependent subclass. The change can be the changing of a non-static non-private field or a method to a static one. In such a scenario the parent class generates an IncompatibleClassChangeError exception at runtime.

This happens because of the disruption introduced to the consistency expected by the JVM at runtime.

We can observe a similar behavior with the following changes in a dependent file:

• A non-final field becomes static
• A class becomes an interface, and vice-versa
• A non-constant field becomes non-static
• Something changed in the signature of a method in the dependent classes

4.2. Changes in Inheritance Patterns

The JVM might also throw the exception when there is a change in the inheritance pattern of a sub-class which is prohibited. This includes scenarios such as implementing an interface without adding the overridden implementations of the required abstract methods, or wrongly implementing a class, etc.

4.3. Different Versions of the Same Dependency in the Classpath

Let’s consider that we’re using Maven for project dependency management and have included two libraries A and B in our classpath by defining them in the pom.xml. However, both of these libraries might depend on different versions of the same third library C.

Therefore, both of these libraries try to pull different versions of the library C into the classpath which differ slightly in structure.

5. Fixing the IncompatibleClassChangeError Exception

Now that we’ve understood what causes the error, let’s see how we can fix and avoid it.

Whenever a dependent library or binary changes, we should recompile the client code against it to understand the compatibility. We have to ensure that compile time class definitions match with the run time class definitions. Maintaining backward binary compatibility is therefore very crucial to ensure that dependent client applications don’t break.

Modern IDEs like IntelliJ already check for changing dependencies in the classpath and warn for incompatible changes.

Tools like Maven also generate a complete dependency graph of all its dependencies and highlight the incompatible or breaking changes in the pom.xml. Furthermore, performing a clean build automatically regenerates sources of all the dependencies which helps in keeping this exception away.

We can also use build tools such as Maven to ensure that duplicate or conflicting versions of the same dependency aren’t present in the classpath. It’s also good practice to continually remove stale class files from the target folder to ensure the latest class files are always present for execution.

6. Conclusion

In this tutorial, we discussed the IncompatibleClassChangeError and highlighted the critical importance of maintaining consistent class structures between compile-time and runtime.

We also discussed ways this error might be generated in an application and how we can effectively prevent this error.