JEP 500, Prepare to Make Final Mean Final, has been completed for JDK 26. This JEP proposes to prepare the Java ecosystem so that it will not allow mutation of fields declared as final via deep reflection, which is generally achieved using the setAccessible() method defined in the AccessibleObject class. This marks the beginning of a deprecation path that will eventually lead to IllegalAccessException being thrown by default in future versions, effectively closing a long-standing loophole in Java’s encapsulation model.
Although final fields have long represented a contract of immutability, Java has historically allowed this contract to be violated through reflection. This long-standing loophole, originally preserved to support object serialization, has accumulated what the OpenJDK team describes as “integrity debt.” Over time, widespread reliance on reflective field mutation by dependency injection, serialization, and mocking frameworks has forced the JVM’s Just-In-Time (JIT) compiler to make conservative assumptions. As a result, optimizations that rely on true immutability, such as constant folding, have been limited. By restoring stronger guarantees around final, the platform can enable more aggressive optimizations and provide developers and architects with more reliable semantics, particularly in concurrent programs.
Under the new behaviour in JDK 26, code that attempts to mutate a final field via deep reflection will still succeed (preserving compatibility), but the JVM will issue a warning by default the first time it occurs per module.
Consider the following example:
java.lang.reflect.Field f = MyClass.class.getDeclaredField("value");
f.setAccessible(true); // deep reflection
f.set(myInstance, 42); // mutates a final field
At runtime, this code will trigger a warning indicating that a final field has been modified reflectively as follows:
WARNING: Final field value in MyClass has been mutated by ...
This is governed by the --illegal-final-field-mutation option, which defaults to warn in JDK 26.
To manage this transition, JEP 500 introduces several runtime modes, similar to other access-control mechanisms introduced in recent Java releases:
--illegal-final-field-mutation=warn(default)
Continue with reflection, but emit a warning.--illegal-final-field-mutation=deny
Fail withIllegalAccessExceptionwhen a reflective mutation is attempted.--illegal-final-field-mutation=allow
Permit the mutation without warnings (not the default).
Developers can also enable reflective final-field mutation selectively at startup using:
java --enable-final-field-mutation=ALL-UNNAMED ...
Or by targeting specific modules, providing a controlled escape hatch for legacy libraries that cannot yet be updated.
To further assist teams in preparing for stricter enforcement, JDK 26 integrates with JDK Flight Recorder (JFR). A new event, jdk.FinalFieldMutation, records every instance of a final field being modified, complete with a stack trace. This allows teams to audit their entire dependency tree for non-compliant behaviour before the “deny” mode becomes the default in a future release.
# Auditing an application for final field mutations
java -XX:StartFlightRecording:filename=audit.jfr -jar my-app.jar
jfr print --events jdk.FinalFieldMutation audit.jfr
With these changes, Java returns to a stricter interpretation of final, closer to its original intent, while still providing a migration path for legacy use cases.
