Compiling across releases and the version trap

Understanding Compiling across releases and the version trap

Every class file opens with the four bytes CAFEBABE, then a minor and a major version number. The major number is the release plus 44, so 52 is Java 8, 55 is Java 11, 61 is Java 17 and 65 is Java 21, and the first thing a JVM does when loading a class is compare that number with the highest it understands. If the number is higher it throws UnsupportedClassVersionError before executing a single instruction, with wording like "class file version 65.0" against "only recognizes class file versions up to 61.0". The check is deliberately one-way: a new JVM reads old class files, an old JVM never reads new ones.

The older way of aiming at an earlier release, -source 11 -target 11, controls only two things: which syntax javac accepts and which number it stamps. The class library on the compile path is still the one inside the JDK that is running javac, so String.formatted (Java 15) or Math.clamp (Java 21) resolve happily and end up as method references inside bytecode stamped 55.0. That artifact loads fine on Java 11 and then throws NoSuchMethodError the first time the offending line runs, because the JVM resolves each call site lazily rather than at startup, which is why this failure so often surfaces in a rare code path in production.

--release N, added in JDK 9, closes the hole by setting source level, target stamp and API surface together: javac compiles against a recorded snapshot of release N's signatures shipped in the JDK's lib/ct.sym, so anything newer becomes a "cannot find symbol" error at the exact call site. That converts the trap from a runtime surprise into a compile failure, which is the entire value of the flag. Coverage is not total, though: reflection, class names built from strings, and dependency jars compiled for a newer release are all invisible to javac, so a green --release N build still deserves one test run on a real JDK N runtime.

import java.io.DataInputStream;
import java.io.InputStream;

public class ClassFileStamp {
    public static void main(String[] args) throws Exception {
        try (InputStream bytes = ClassFileStamp.class.getResourceAsStream("ClassFileStamp.class");
             DataInputStream in = new DataInputStream(bytes)) {
            int magic = in.readInt();
            int minor = in.readUnsignedShort();
            int major = in.readUnsignedShort();
            System.out.printf("magic %X, class file version %d.%d%n", magic, major, minor);
            System.out.println("stamped for Java " + (major - 44));
        }
        System.out.println("this JVM loads up to " + System.getProperty("java.class.version"));
    }
}

Worked examples

public class Baseline {
    public static void main(String[] args) {
        String template = "score=%d";
        String label = template.formatted(72);
        int safe = Math.clamp(72, 0, 60);
        System.out.println(label + " " + safe);
    }
}

public class Report {
    public static void main(String[] args) {
        System.out.println("report generated");
    }
}

Important notes

Common mistakes

Try it yourself