AVRO-4189: [Java] Use ClassUtils.forName() in FastReaderBuilder for consistency

[iemejia]

I noticed that FastReaderBuilder.findClass() was using data.getClassLoader().loadClass() directly, bypassing ClassUtils.forName() which is used everywhere else in the codebase. This change aligns FastReaderBuilder with the standard class loading path and adds tests for class loading behavior.

What is the purpose of the change

(For example: This pull request improves file read performance by buffering data, fixing AVRO-XXXX.)

Verifying this change

(Please pick one of the following options)

This change is a trivial rework / code cleanup without any test coverage.

(or)

This change is already covered by existing tests, such as (please describe tests).

(or)

This change added tests and can be verified as follows:

(example:)

• Extended interop tests to verify consistent valid schema names between SDKs
• Added test that validates that Java throws an AvroRuntimeException on invalid binary data
• Manually verified the change by building the website and checking the new redirect

Documentation

• Does this pull request introduce a new feature? (yes / no)
• If yes, how is the feature documented? (not applicable / docs / JavaDocs / not documented)

[gszadovszky]

Thanks a lot for working on this, @iemejia.

[gszadovszky]

I'm wondering if it is a good practice here to swallow the SecurityException. It will be hard to analyze why the class loading is not working while the SecurityException contains a comprehensive explanation. WDYT?

[iemejia]

Oh you have a point I somehow did not remember that SecurityException was a RuntimeException. I will fix it.

[iemejia]

Done @gszadovszky PTAL again, thx

[vkolomeyko]

⚠️ @iemejia @gszadovszky
Avro version 1.12.2 has just been released. When upgrading our applications from version 1.12.1 we started seeing unexpected exceptions like:

java.lang.SecurityException: Forbidden com.company.our.own.Class!
  This class is not trusted to be included in Avro schemas.
    at org.apache.avro.util.ClassSecurityValidator.validate(ClassSecurityValidator.java:60)
    at org.apache.avro.util.ClassUtils.forName(ClassUtils.java:99)
    at org.apache.avro.specific.SpecificData.getForSchema(SpecificData.java:215)
    at org.apache.avro.specific.SpecificDatumWriter.<init>(SpecificDatumWriter.java:47)

I.e. version 1.12.2 created an unwanted effect which now requires setting org.apache.avro.SERIALIZABLE_PACKAGES to be able to work with this version of the library.

More details (AI-generated):

Regression in 1.12.2: SpecificDatumReader/Writer reject the application's own generated classes

Project: Avro · Component: java · Affects Version: 1.12.2 (and current default branch)
Type: Bug · Suggested Priority: Critical — breaks ordinary API usage in a patch release
Introduced by: AVRO-4189 (e0217aefd on main, 3b764e1a on the 1.12 branch, PR #3525)

Summary

Since 1.12.2, constructing a SpecificDatumReader or SpecificDatumWriter for an ordinary
application-generated SpecificRecord class throws SecurityException unless the application
first allowlists its own packages via org.apache.avro.SERIALIZABLE_PACKAGES.

Three of the four standard constructors are affected, including SpecificDatumReader(Class), where
the class is supplied programmatically by the application and never derived from schema data:

Constructor	1.12.1	1.12.2
new SpecificDatumWriter<>(MyRecord.SCHEMA$)	OK	SecurityException
new SpecificDatumWriter<>(MyRecord.class)	OK	OK
new SpecificDatumReader<>(MyRecord.SCHEMA$)	OK	SecurityException
new SpecificDatumReader<>(MyRecord.class)	OK	SecurityException

No release note or migration entry mentions that applications must now allowlist their own
packages, and 1.12.2 is a patch release.

Reproducer

Two files, avro + its runtime deps on the classpath. No third-party libraries.

package com.example;

import org.apache.avro.Schema;
import org.apache.avro.specific.SpecificRecord;

public class MyRecord implements SpecificRecord {
  public static final Schema SCHEMA$ = new Schema.Parser().parse(
      "{\"type\":\"record\",\"name\":\"MyRecord\",\"namespace\":\"com.example\","
          + "\"fields\":[{\"name\":\"id\",\"type\":\"string\"}]}");

  public CharSequence id;

  @Override public Schema getSchema() { return SCHEMA$; }
  @Override public Object get(int field) { return id; }
  @Override public void put(int field, Object value) { this.id = (CharSequence) value; }
}

import com.example.MyRecord;
import org.apache.avro.specific.SpecificDatumWriter;

public class Repro {
  public static void main(String[] args) {
    new SpecificDatumWriter<>(MyRecord.SCHEMA$);   // OK on 1.12.1, SecurityException on 1.12.2
  }
}

Actual output on 1.12.2:

java.lang.SecurityException: Forbidden com.example.MyRecord! This class is not trusted to be
included in Avro schemas. You may either use the system properties
org.apache.avro.SERIALIZABLE_CLASSES and org.apache.avro.SERIALIZABLE_PACKAGES to set the comma
separated list of the classes or packages you trust, or you can set them via the API (see
org.apache.avro.util.ClassSecurityValidator).
  at org.apache.avro.util.ClassSecurityValidator$ClassSecurityPredicate.forbiddenClass(ClassSecurityValidator.java:106)
  at org.apache.avro.util.ClassSecurityValidator.validate(ClassSecurityValidator.java:60)
  at org.apache.avro.util.ClassUtils.forName(ClassUtils.java:99)
  at org.apache.avro.util.ClassUtils.forName(ClassUtils.java:72)
  at org.apache.avro.specific.SpecificData.lambda$getClass$2(SpecificData.java:393)
  at org.apache.avro.specific.SpecificData.getClass(SpecificData.java:391)
  at org.apache.avro.specific.SpecificData.getForSchema(SpecificData.java:215)
  at org.apache.avro.specific.SpecificDatumWriter.<init>(SpecificDatumWriter.java:47)

Expected: the writer is constructed, as in 1.12.1 and every earlier release.

Adding -Dorg.apache.avro.SERIALIZABLE_PACKAGES=com.example makes 1.12.2 behave as before, which
confirms the validator is the cause.

Root cause

AVRO-4189 moved the trusted-classes allowlist out of SpecificDatumReader into the new
org.apache.avro.util.ClassSecurityValidator, and wired it into the private
ClassUtils.forName(String, ClassLoader) helper:

   private static Class<?> forName(String className, ClassLoader classLoader) {
     ...
-        c = Class.forName(className, true, classLoader);
+        // Load the class without initializing it so we can distinguish between
+        // ClassNotFoundException and SecurityException (that may be thrown by the
+        // validator).
+        c = Class.forName(className, false, classLoader);
+        ClassSecurityValidator.validate(c);

That private helper backs every public ClassUtils.forName overload, so the check now runs on
every class resolution in the library.

Before the change, the allowlist lived in SpecificDatumReader.checkSecurity(String) with exactly
one call site — getPropAsClass(), which only runs when resolving the java-class /
java-key-class / java-element-class schema property while reading:

     try {
-      checkSecurity(name);
       Class clazz = ClassUtils.forName(getData().getClassLoader(), name);

-  private void checkSecurity(String className) throws ClassNotFoundException {
-    ...
-    throw new SecurityException("Forbidden " + className + "! This class is not trusted to be included in Avro "
-        + "schemas using java-class. Please set the system property org.apache.avro.SERIALIZABLE_CLASSES to the comma "

Note the removed message said "...included in Avro schemas using java-class". The new message
drops that qualifier, matching the fact that the check is no longer java-class-scoped.

Why the new call site is too broad

The allowlist exists to stop an untrusted schema from naming an arbitrary class for Avro to load
and instantiate. Two of the newly-affected paths carry no such input:

1. SpecificDatumWriter construction. SpecificDatumWriter.<init>(Schema) →
   SpecificData.getForSchema → SpecificData.getClass(Schema) → ClassUtils.forName. This is
   serialization: the application is writing its own objects, and the class name comes from the
   generated schema the application itself ships. There is nothing to defend against.
2. SpecificDatumReader(Class). The application hands over a Class literal. Rejecting it
   means Avro distrusts a class reference the caller supplied directly, not one it parsed.

Only DEFAULT_TRUSTED_CLASSES is trusted out of the box — a fixed 16-entry JDK list
(java.lang.Boolean, CharSequence, String, java.math.BigDecimal, …) — while
SERIALIZABLE_CLASSES and SERIALIZABLE_PACKAGES default to empty. So the default posture is
"deny every application class".

Why the test suite did not catch it

The same commit added a global systemPropertyVariables block to the surefire configuration in
lang/java/pom.xml, applied to every module:

<org.apache.avro.SERIALIZABLE_PACKAGES>
  org.apache.avro,
  test
</org.apache.avro.SERIALIZABLE_PACKAGES>

with matching additions in lang/java/avro/src/it/pom.xml and
lang/java/interop-data-test/src/it/check/pom.xml. Allowlisting Avro's own test packages made the
suite green and hid the fact that callers outside those packages now need the same treatment. The
commit message ("Fix system property settings in pom") reads as a build fix rather than a signal of
an API behaviour change.

Real-world impact

This took down Kafka publishing in a production payments service for ~63 minutes. The service
serialises avro4k records via AWS's schema-registry-serde; avro4k's Record interface extends
both GenericRecord and SpecificRecord, so the AWS serializer takes its SPECIFIC_RECORD branch
and constructs SpecificDatumWriter(Schema).

Diagnosis was much harder than it should have been, for a reason worth flagging: AWS's
AvroSerializer.getSpecificDatumWriter is annotated with Lombok @SneakyThrows and AWS ships
lombok as provided. The generated catch (Throwable) → lombok.Lombok.sneakyThrow rethrow
therefore failed to link, and the SecurityException was replaced by
NoClassDefFoundError: lombok/Lombok with the original cause discarded. That masking is AWS's bug,
not Avro's, but it illustrates how an unexpected SecurityException from a constructor can surface
somewhere unrecognisable.

Workaround

-Dorg.apache.avro.SERIALIZABLE_PACKAGES=com.mycompany

or ClassSecurityValidator.setGlobal(...) before first use. Both require every affected application
to opt out of a check it did not ask for.

Suggested resolutions

In rough order of preference:

1. Restore the narrow scope. Keep ClassUtils.forName neutral and validate at the point where
   an untrusted schema property is turned into a class — i.e. back at
   SpecificDatumReader.getPropAsClass() — retaining ClassSecurityValidator as the reusable
   policy object AVRO-4189 introduced.
2. Exempt caller-supplied and schema-owned class resolution. Add a non-validating resolution path
   used by SpecificData.getClass(Schema) / getForSchema and by the Class-taking reader and
   writer constructors, leaving validation on the decode path.
3. At minimum, if the broad scope is intentional: treat it as a breaking change — document it in
   the release notes and migration guide, and consider defaulting the validator to permissive with
   an explicit opt-in, so a patch upgrade cannot break working applications silently.

[iemejia]

You are right, @vkolomeyko. This is a breaking change, and we need to communicate it clearly. We somehow forgot to highlight this @RyanSkraba (my excuses for not reminding you about it).

This solution is somewhat radical because it now requires users to explicitly opt in to the classes they consider safe to process. The core issue is that a carefully crafted Avro Schema could potentially execute arbitrary code during deserialization. This is a well-known class of vulnerabilities in Java deserialization and has been reported to us multiple times, most recently in the context of CVE-2025-30065.

For context, the previous changes introduced in issues #3525 and #3538 implemented most of the required infrastructure for this protection. However, the ClassLoader was not correctly validating classes, which is what this PR fixes.

The downside is that Avro users must now explicitly declare which classes are trusted, a requirement that many users are/were not expecting. The upside is significantly improved security, as it prevents unexpected or malicious code execution through schema deserialization.

We've been investing considerable effort in hardening Avro, especially given the recent surge in security reports and vulnerability disclosures. This change is another step in that direction. Sorry for the inconvenience.

[RyanSkraba]

Hello! I've been writing the release notes (currently in this PR): #3945 and I've added a Breaking Changes section to address this.

I agree this should have been called out sooner, and I shouldn't have released the 1.12.2 maven artifacts before writing the release notes.

[steam0]

@RyanSkraba, isnt org.apache.avro.SERIALIZABLE_PACKAGES deprecated ref:

#3376

[joebowbeer]

@RyanSkraba, isnt org.apache.avro.SERIALIZABLE_PACKAGES deprecated ref:

#3376

#3945 (comment)

[RyanSkraba]

I've rewritten the breaking changes section at #3945 -- is it clearer to follow?

As far as I can tell, the SERIALIZABLE_PACKAGES system property was moved to a different class and isn't marked deprecated any more.

To be clear, I have zero objection to rapidly doing a release 1.12.3 that relaxes instantiation in a safe and controlled way that makes Avro more usable, and less breaking-changeable. Please bring up any suggestions on the mailing list. At this point, I'm looking to wrap up the 1.12.2 release!