Prepare for final field mutation warning under Java 26

[TheDGOfficial]

Gson version

2.13.2

Java / Android version

openjdk version "26" 2026-03-17
OpenJDK Runtime Environment (build 26+35-2893)
OpenJDK 64-Bit Server VM (build 26+35-2893, mixed mode, sharing)

Used tools

• Maven; version:
• Gradle; version:
• ProGuard (attach the configuration file please); version:
• ...

Description

A final field mutation warning appears when running under Java 26.

Expected behavior

No warnings expected.

Actual behavior

Warning appears.

Reproduction steps

import com.google.gson.Gson;

class ClassWithFinalField {
    final String finalField;

    ClassWithFinalField(String s) {
        finalField = s;
    }

    void print() {
        IO.println(finalField);
    }
}

void main() {
    new Gson().fromJson(
        """
        {"finalField":"Hello, world!"}
        """
    , ClassWithFinalField.class).print();
}

1. Run with Java 25; no warnings, mutation works.
2. Run with Java 26; warnings emitted, mutation still works but is going to be disallowed in a future release.

To run, download gson 2.13.2 jar from maven central, save the code above to a file named TestFinalFieldModification.java, and run the following:

java -cp gson-2.13.2.jar TestFinalFieldModification.java

For Java 26, replace java with the path to java 26 binary, like ./jdk-26/bin/java

*Java 26 is still in early access but is going to reach general availability in approx. 1 week from now on so I wanted to create the issue in advance.

Exception stack trace

WARNING: Final field finalField in class TestFinalFieldModification$ClassWithFinalField has been mutated reflectively by class com.google.gson.internal.bind.ReflectiveTypeAdapterFactory$2 in unnamed module @59fd97a8 (file:/home/mustafa/%c4%b0ndirilenler/gson-2.13.2.jar)
WARNING: Use --enable-final-field-mutation=ALL-UNNAMED to avoid a warning
WARNING: Mutating final fields will be blocked in a future release unless final field mutation is enabled

When using --illegal-final-field-mutation=debug:

Final field finalField in class TestFinalFieldModification$ClassWithFinalField has been mutated reflectively by class com.google.gson.internal.bind.ReflectiveTypeAdapterFactory$2 in unnamed module @795cd85e (file:/home/mustafa/%c4%b0ndirilenler/gson-2.13.2.jar)
	at java.base/java.lang.reflect.Field.postSetFinal(Field.java:1534)
	at java.base/java.lang.reflect.Field.setFinal(Field.java:1449)
	at java.base/java.lang.reflect.Field.set(Field.java:909)
	at com.google.gson.internal.bind.ReflectiveTypeAdapterFactory$2.readIntoField(ReflectiveTypeAdapterFactory.java:282)
	at com.google.gson.internal.bind.ReflectiveTypeAdapterFactory$FieldReflectionAdapter.readField(ReflectiveTypeAdapterFactory.java:559)
	at com.google.gson.internal.bind.ReflectiveTypeAdapterFactory$Adapter.read(ReflectiveTypeAdapterFactory.java:517)
	at com.google.gson.Gson.fromJson(Gson.java:1358)
	at com.google.gson.Gson.fromJson(Gson.java:1259)
	at com.google.gson.Gson.fromJson(Gson.java:1169)
	at com.google.gson.Gson.fromJson(Gson.java:1106)
	at TestFinalFieldModification.main(TestFinalFieldModification.java:16)
	at jdk.compiler/com.sun.tools.javac.launcher.SourceLauncher.execute(SourceLauncher.java:262)
	at jdk.compiler/com.sun.tools.javac.launcher.SourceLauncher.run(SourceLauncher.java:138)
	at jdk.compiler/com.sun.tools.javac.launcher.SourceLauncher.main(SourceLauncher.java:76)

When using --illegal-final-field-mutation=deny (going to be the default behaviour in a later release):

Exception in thread "main" java.lang.RuntimeException: Unexpected IllegalAccessException occurred (Gson 2.13.2). Certain ReflectionAccessFilter features require Java >= 9 to work correctly. If you are not using ReflectionAccessFilter, report this to the Gson maintainers.
	at com.google.gson.internal.reflect.ReflectionHelper.createExceptionForUnexpectedIllegalAccess(ReflectionHelper.java:201)
	at com.google.gson.internal.bind.ReflectiveTypeAdapterFactory$Adapter.read(ReflectiveTypeAdapterFactory.java:523)
	at com.google.gson.Gson.fromJson(Gson.java:1358)
	at com.google.gson.Gson.fromJson(Gson.java:1259)
	at com.google.gson.Gson.fromJson(Gson.java:1169)
	at com.google.gson.Gson.fromJson(Gson.java:1106)
	at TestFinalFieldModification.main(TestFinalFieldModification.java:16)
Caused by: java.lang.IllegalAccessException: class com.google.gson.internal.bind.ReflectiveTypeAdapterFactory$2 (in unnamed module @59fd97a8) cannot set final field TestFinalFieldModification$ClassWithFinalField.finalField (in unnamed module @f5ac9e4), unnamed module @59fd97a8 is not allowed to mutate final fields
	at java.base/java.lang.reflect.Field.preSetFinal(Field.java:1504)
	at java.base/java.lang.reflect.Field.setFinal(Field.java:1447)
	at java.base/java.lang.reflect.Field.set(Field.java:909)
	at com.google.gson.internal.bind.ReflectiveTypeAdapterFactory$2.readIntoField(ReflectiveTypeAdapterFactory.java:282)
	at com.google.gson.internal.bind.ReflectiveTypeAdapterFactory$FieldReflectionAdapter.readField(ReflectiveTypeAdapterFactory.java:559)
	at com.google.gson.internal.bind.ReflectiveTypeAdapterFactory$Adapter.read(ReflectiveTypeAdapterFactory.java:517)
	at com.google.gson.Gson.fromJson(Gson.java:1358)
	at com.google.gson.Gson.fromJson(Gson.java:1259)
	at com.google.gson.Gson.fromJson(Gson.java:1169)
	at com.google.gson.Gson.fromJson(Gson.java:1106)
	at TestFinalFieldModification.main(TestFinalFieldModification.java:16)
	at java.base/jdk.internal.reflect.DirectMethodHandleAccessor.invoke(DirectMethodHandleAccessor.java:104)
	at java.base/java.lang.reflect.Method.invoke(Method.java:565)
	at jdk.compiler/com.sun.tools.javac.launcher.SourceLauncher.execute(SourceLauncher.java:262)
	at jdk.compiler/com.sun.tools.javac.launcher.SourceLauncher.run(SourceLauncher.java:138)
	at jdk.compiler/com.sun.tools.javac.launcher.SourceLauncher.main(SourceLauncher.java:76)

References

JEP 500: Prepare to Make Final Mean Final

[utsavatwork]

Hi @TheDGOfficial,
Can I try and take this up?

[TheDGOfficial]

Hi @TheDGOfficial, Can I try and take this up?

Sure, I'd like to note the section regarding Serializable interface requirement from the JEP though:

The sun.reflect.ReflectionFactory class only supports the deserialization of objects whose classes implement the java.io.Serializable interface. This limitation balances the interests of developers using serialization libraries with the wider interest of all developers in having correct and efficient execution. It ensures that the JVM, when performing optimizations such as constant folding, is not unduly constrained in the assumptions it can make: It must assume that final fields in Serializable objects are potentially mutable, but it can also assume that final fields in all other objects — which are the vast majority — are permanently immutable.

So even though the JEP recommends switching over to ReflectionFactory it might not be as straightforward as Gson currently does not require the Serializable interface to be implemented.

[utsavatwork]

Thanks @TheDGOfficial.
Sure, I'll check the JEP thing.

[eamonnmcmanus]

We're well aware of the issue here. Unfortunately, the whole modifying-final-fields thing is deeply ingrained into Gson. I think the best we can do is:

1. Update the exception message to take the JEP 500 changes into consideration. It could suggest running with --enable-final-field-mutation for example.
2. Add some documentation about alternatives to reflection-based serialization and deserialization, with code examples. Alternatives include:
   • Remove final from fields. (And also add a no-arg constructor while you are at it.)
   • Use Java records.
   • Use Kotlin data classes with a TypeAdapterFactory that understands those. Google has an internal one of these that we could publish.
   • Write a custom TypeAdapter (or JsonDeserializer, which is easier to implement), for each affected class.

We've been steering people away from the reflection-based serialization and deserialization, but perhaps not strongly enough. It is problematic not only for the immediate reason here but also because it derives a public (JSON) API for a class based on its private fields, and it does so for any class, not just classes explicitly designed for Gson.

We could also try to use ReflectionFactory for classes that do implement Serializable. I'm not sure if that would be worthwhile, though. If you need to modify your value classes to put Serializable on them, maybe you should make them be records instead.

[utsavatwork]

Noted @eamonnmcmanus,

I've started working on the PR to make the 2 changes you've listed here.

1. Dedicated exception handeling for the scenario where final fields are being mutated. In the exception message, I'll also include the JEP 500 update about the same.
2. Update documentation to add alternative approaches and encourage users to not use final fields.

Anything I'm missing here?

[eamonnmcmanus]

@utsavatwork feel free to do the first thing (exception handling). However I plan to make the documentation changes based on extensive experience with Google's internal code.

[utsavatwork]

@eamonnmcmanus @TheDGOfficial
Raised this PR. Debugging into why JDK 21 Build is failing. Meanwhile, You can review it as well.