Version Compatibility

What is Version Compatibility — and What Actually Enforces It?

The previous page showed how --release controls what javac is willing to compile. This page is about the other side of that same coin: what the JVM does the moment it actually tries to load a compiled class file, and exactly why it accepts some and rejects others. Every class file carries an explicit major version number, and the rule the JVM enforces is strict and one-directional — a JVM runs class files from its own version or earlier, never later. There's no negotiation, no partial compatibility, no "it might work" — the check happens at class-loading time, before a single instruction of your code executes.

// BEFORE — deploying without checking the target JVM at all
$ java -jar order-service.jar
Error: A JNI error has occurred, please check your installation and try again
Exception in thread "main" java.lang.UnsupportedClassVersionError:
  com/shop/OrderService has been compiled by a more recent version of the
  Java Runtime (class file version 65.0), this version of the Java Runtime
  only recognizes class file versions up to 61.0
// Compiled with --release 21 (class file major version 65), deployed to a
// server still running Java 17 (which only accepts up to major version 61).
// This fails at the exact moment the JVM tries to load the class — not on
// the first line of actual application logic.

// AFTER — verifying the class file version BEFORE shipping
$ javap -verbose OrderService.class | grep "major version"
  major version: 65
// 65 means Java 21+ only. Compare directly against `java -version` on the
// actual target server before deploying — this one check would have caught
// the mismatch in a five-second local command, not a production incident.

Class File Version Numbers — the Mechanism Itself

Every .class file's first eight bytes are structural: the 4-byte magic number 0xCAFEBABE (identifying it as Java bytecode at all), followed by a 2-byte minor version and a 2-byte major version. The major version is what the JVM checks against its own maximum supported version before doing anything else — the pattern is a flat, predictable increment: Java 8 is major version 52, and every release since adds exactly 1.

Checking Compatibility Before You Deploy

From the command line

javap -verbose OrderService.class | grep "major version"
#   major version: 61

java -version
# openjdk version "17.0.9" ...  — compare this directly against the class file's major version

Programmatically — reading the raw bytes yourself

public class ClassVersionChecker {
    public static void main(String[] args) throws Exception {
        try (DataInputStream dis = new DataInputStream(
                new FileInputStream("OrderService.class"))) {
            int magic = dis.readInt();               // must be 0xCAFEBABE
            int minor = dis.readUnsignedShort();
            int major = dis.readUnsignedShort();
            System.out.println("Major version: " + major);
        }
    }
}

Checking the running JVM's own version

String version = System.getProperty("java.version");

// Java 9+ — structured version access, no string parsing needed
Runtime.Version runtimeVersion = Runtime.version();
System.out.println("Feature: " + runtimeVersion.feature());   // e.g. 17
System.out.println("Update: " + runtimeVersion.update());     // e.g. 9

Multi-Release JARs — One Artifact, Several Bytecode Versions

Java 9 introduced Multi-Release JARs (JEP 238): a single JAR that ships a baseline class alongside version-specific overrides, letting a library use a newer, better implementation automatically on newer JVMs while still working correctly on older ones.

catalog-utils.jar
├── META-INF/
│   ├── MANIFEST.MF              # declares Multi-Release: true
│   └── versions/
│       ├── 11/com/shop/Helper.class   # used on Java 11+
│       └── 17/com/shop/Helper.class   # used on Java 17+ — takes priority over the 11 version there
└── com/shop/Helper.class        # base version — used on anything below 11

<!-- pom.xml -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-jar-plugin</artifactId>
    <configuration>
        <archive>
            <manifestEntries>
                <Multi-Release>true</Multi-Release>
            </manifestEntries>
        </archive>
    </configuration>
</plugin>

Common Compatibility Issues

Removed APIs

// javax.xml.bind (JAXB) was removed from the JDK itself in Java 11
import javax.xml.bind.JAXBContext;   // won't compile on 11+ without an explicit dependency

// Migration: add the Jakarta EE equivalent explicitly
// <dependency>
//     <groupId>jakarta.xml.bind</groupId>
//     <artifactId>jakarta.xml.bind-api</artifactId>
// </dependency>

Reflective access under the module system (Java 9+)

// Worked without complaint on Java 8:
Field field = SomeClass.class.getDeclaredField("internalCache");
field.setAccessible(true);   // may now fail — strong encapsulation restricts this by default

// Explicit opt-in required:
// --add-opens java.base/java.lang=ALL-UNNAMED

Compatibility Testing Strategies

Maven Toolchains — build against a specific, real JDK

<!-- pom.xml -->
<plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-toolchains-plugin</artifactId>
    <executions>
        <execution><goals><goal>toolchain</goal></goals></execution>
    </executions>
    <configuration>
        <toolchains><jdk><version>17</version></jdk></toolchains>
    </configuration>
</plugin>

CI matrix testing — every LTS you actually claim to support

# GitHub Actions
jobs:
  test:
    strategy:
      matrix:
        java: [17, 21, 25]
    steps:
      - uses: actions/setup-java@v4
        with:
          java-version: ${{ matrix.java }}
          distribution: 'temurin'
      - run: mvn test

Best Practices and Common Pitfalls

Interview Questions