quarkusio/quarkus · error · IllegalStateException

Unable to create new instance for ${clazz}

Error message

Unable to create new instance for ${clazz}

What it means

In the Quarkus Avro GraalVM substitution (AvroSubstitutions), a Function that instantiates a class reflectively via constructor.newInstance wraps any reflective failure in an IllegalStateException naming the class. This runs at native-image runtime when Avro needs to create a specific record instance from a value; failures mean the constructor is inaccessible or the class/constructor was not registered for reflection.

Source

Thrown at extensions/avro/runtime/src/main/java/io/quarkus/avro/runtime/graal/AvroSubstitutions.java:83

    }

}

@TargetClass(className = "org.apache.avro.reflect.ReflectionUtil")
final class Target_org_apache_avro_reflect_ReflectionUtil {

    @Substitute
    public static <V, R> Function<V, R> getConstructorAsFunction(Class<V> parameterClass, Class<R> clazz) {
        // Cannot use the method handle approach as it uses ProtectionDomain which got removed.
        try {
            Constructor<R> constructor = clazz.getConstructor(parameterClass);
            return new Function<V, R>() {
                @Override
                public R apply(V v) {
                    try {
                        return constructor.newInstance(v);
                    } catch (Exception e) {
                        throw new IllegalStateException("Unable to create new instance for " + clazz, e);
                    }
                }
            };
        } catch (Throwable t) {
            // if something goes wrong, do not provide a Function instance
            return null;
        }
    }
}

class AvroSubstitutions {
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Annotate the affected class with @io.quarkus.runtime.annotations.RegisterForReflection (and its field types)
2. Check the chained cause: IllegalArgumentException means wrong constructor arity/type; IllegalAccessException means constructor is not public
3. Ensure the class has a constructor matching the expected single-value signature
4. Rebuild the native image after adding reflection registration

Example fix

// before
public class MyDto { public MyDto(String v) {...} } // no reflection registration
// after
@RegisterForReflection
public class MyDto { public MyDto(String v) {...} }

// ensure native reflection registration before building native image
boolean registered = MyDto.class.isAnnotationPresent(
    io.quarkus.runtime.annotations.RegisterForReflection.class);
if (!registered && System.getProperty("native.image", "false").equals("true")) {
    throw new IllegalStateException("Add @RegisterForReflection to " + MyDto.class.getName());
}

try {
    R value = avroReadNext(reader);
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Unable to create new instance for")) {
        log.error("Register " + e.getMessage().replace("Unable to create new instance for ", "")
            + " for reflection in native mode");
    }
    throw e;
}

When it happens

Trigger: At native runtime, Avro's ReflectDatumReader or similar needs to construct an instance and the substituted factory's Constructor.newInstance(value) throws (IllegalAccessException, IllegalArgumentException, or InstantiationException wrapped as Exception).

Common situations: Native-image build missing @RegisterForReflection on the record/POJO; constructor signature mismatch (e.g. single-arg constructor absent); class removed by native reachability analysis.

Related errors

• Unable to find the following conversion class: ${customConve
• .pfa font files are not supported. Use TrueType fonts, i.e.
• .pfb font files are not supported. Use TrueType fonts, i.e.
• Unable to set tmp java.home for FontConfig Quarkus AWT usage
• JMX is not available in native images.

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/cf04c6f42b78d78e. Report an issue: GitHub.