quarkusio/quarkus · error · IllegalArgumentException

Unable to instantiate integrator <integratorClass>

Error message

Unable to instantiate integrator <integratorClass>

What it means

FastBootMetadataBuilder collects additional Hibernate Integrator classes supplied via configuration (hibernate.integrator.provider / additional integrators) and instantiates them reflectively with a no-arg constructor. If instantiation fails (missing public no-arg constructor, exception in constructor, or class init failure), the builder wraps the cause in this IllegalArgumentException.

Source

Thrown at extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/boot/FastBootMetadataBuilder.java:493

    private Dialect extractDialect() {
        DialectFactory service = standardServiceRegistry.getService(DialectFactory.class);
        QuarkusStaticInitDialectFactory casted = (QuarkusStaticInitDialectFactory) service;
        return casted.getDialect();
    }

    private Collection<Integrator> getIntegrators() {
        LinkedHashSet<Integrator> integrators = new LinkedHashSet<>();
        if (isHibernateValidatorPresent) {
            integrators.add(new BeanValidationIntegrator());
        }
        integrators.add(new CollectionCacheInvalidator());

        for (Class<? extends Integrator> integratorClass : additionalIntegrators) {
            try {
                integrators.add(integratorClass.getConstructor().newInstance());
            } catch (Exception e) {
                throw new IllegalArgumentException("Unable to instantiate integrator " + integratorClass, e);
            }
        }

        return integrators;
    }

    @SuppressWarnings("rawtypes")
    private static class MergedSettings {
        private final Map configurationValues = new ConcurrentHashMap(16, 0.75f, 1);
        private List<CacheRegionDefinition> cacheRegionDefinitions;

        private MergedSettings() {
        }

        public Map getConfigurationValues() {
            return configurationValues;
        }

View on GitHub (pinned to e1c734241f)

Solutions

  1. Give the integrator a public no-argument constructor.
  2. Check the nested 'Caused by' for the real failure (constructor exception, NoClassDefFoundError, etc.).
  3. Register the integrator via an extension build step (AdditionalJaxbMappingBuildItem / integrator build item) instead of reflective instantiation.
  4. Ensure the integrator class is on the runtime classpath and its dependencies are present (e.g., mark beans @Injectable or avoid DI inside the constructor).

Example fix

// before
public class MyIntegrator implements Integrator {
    public MyIntegrator(SomeService svc) { ... } // no no-arg ctor
}
// after
public class MyIntegrator implements Integrator {
    public MyIntegrator() { } // reflectively instantiable
    @Override public void integrate(...) { ... }
}
Defensive patterns

Strategy: validation

Validate before calling

static <T extends Integrator> void validateIntegrator(Class<T> c) throws Exception {
    c.getConstructor(); // throws NoSuchMethodException early if no public no-arg ctor
    c.getDeclaredConstructor().newInstance(); // surface ctor exceptions before boot
}

Try / catch

try {
    integratorClass.getConstructor().newInstance();
} catch (IllegalArgumentException e) {
    log.error("Integrator " + integratorClass + " must have a public no-arg constructor", e.getCause());
}

Prevention

When it happens

Trigger: Configuring an integrator class via quarkus.hibernate.orm.additional-integrators (or pu-level equivalent) whose class lacks a public no-argument constructor, throws in its constructor, or fails static initialization when getConstructor().newInstance() is called.

Common situations: Typos in the integrator class name that resolve to another class; integrators written with constructor dependencies (DI) that plain reflective instantiation cannot satisfy; integrator constructors throwing because Quarkus services aren't available yet at static-init time.

Related errors

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