quarkusio/quarkus · error · java.lang.IllegalStateException

Unable to instantiate SectionHelperFactory: <engineConfigCla

Error message

Unable to instantiate SectionHelperFactory: <engineConfigClass>

What it means

During template analysis QuteProcessor reflectively instantiates every SectionHelperFactory implementation registered via quarkus.qute.engine-config / engine configuration classes on the TCCL. If loadClass or newInstance fails (missing no-arg constructor, classloading problem, constructor throwing, wrong type), the build aborts with this IllegalStateException wrapping the cause.

Source

Thrown at extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/QuteProcessor.java:693

            }
        }

        // Register additional section factories and parser hooks
        if (engineConfigurations.isPresent()) {
            // Use the deployment class loader - it can load application classes; it's non-persistent and isolated
            ClassLoader tccl = Thread.currentThread().getContextClassLoader();
            IndexView index = beanArchiveIndex.getIndex();

            for (ClassInfo engineConfigClass : engineConfigurations.get().getConfigurations()) {
                if (Types.isImplementorOf(engineConfigClass, Names.SECTION_HELPER_FACTORY, index)) {
                    try {
                        Class<?> sectionHelperFactoryClass = tccl.loadClass(engineConfigClass.toString());
                        SectionHelperFactory<?> factory = (SectionHelperFactory<?>) sectionHelperFactoryClass
                                .getDeclaredConstructor().newInstance();
                        builder.addSectionHelper(factory);
                        LOGGER.debugf("SectionHelperFactory registered during template analysis: %s", engineConfigClass);
                    } catch (Exception e) {
                        throw new IllegalStateException("Unable to instantiate SectionHelperFactory: " + engineConfigClass, e);
                    }
                } else if (Types.isImplementorOf(engineConfigClass, Names.PARSER_HOOK, index)) {
                    try {
                        Class<?> parserHookClass = tccl.loadClass(engineConfigClass.toString());
                        ParserHook parserHook = (ParserHook) parserHookClass.getDeclaredConstructor().newInstance();
                        builder.addParserHook(parserHook);
                        LOGGER.debugf("ParserHook registered during template analysis: %s", engineConfigClass);
                    } catch (Exception e) {
                        throw new IllegalStateException("Unable to instantiate ParserHook: " + engineConfigClass, e);
                    }
                }
            }
        }

        builder.computeSectionHelper(name -> {
            // Create a dummy section helper factory for an unknown section that could be potentially registered at runtime
            return new SectionHelperFactory<SectionHelper>() {
                @Override

View on GitHub (pinned to e1c734241f)

Solutions

1. Give the factory a public no-arg constructor and ensure its constructor/static init does not throw
2. Check the wrapped 'Caused by' in the stack trace for the real failure (ClassNotFound vs InvocationTargetException)
3. Make sure the factory class lives in a runtime module of the same Quarkus/Qute version and is on the application classpath
4. If the class is not a factory, fix the engine configuration registration that lists it

Example fix

// before
public class MyFactory implements SectionHelperFactory<MyHelper> {
    public MyFactory(String bad) { ... } // no no-arg ctor
}
// after
public class MyFactory implements SectionHelperFactory<MyHelper> {
    public MyFactory() { }
}

// verify the factory can be instantiated before the build
Class<?> c = Class.forName("com.acme.MySectionFactory", true, Thread.currentThread().getContextClassLoader());
if (!SectionHelperFactory.class.isAssignableFrom(c)) throw new IllegalStateException("Not a factory");
c.getDeclaredConstructor().setAccessible(true);
Object f = c.getDeclaredConstructor().newInstance(); // fails early with clear cause

When it happens

Trigger: analyzeTemplates iterates engine-config classes; a class implementing SectionHelperFactory is loaded with tccl.loadClass() and getDeclaredConstructor().newInstance(); any Exception (ClassNotFoundException, InstantiationException, InvocationTargetException) is wrapped.

Common situations: Custom SectionHelperFactory with no public no-arg constructor; factory constructor throwing (e.g. static init failure); runtime class in a module not visible to the deployment TCCL; class implementing the interface from a different/incompatible Qute version.

Related errors

• Unable to instantiate ParserHook: <engineConfigClass>
• Invalid Flyway callback. It shouldn't be abstract and must h
• Message bundle name [%s] declared on %s must be a valid name
• Message bundle interface name conflict - [%s] is used for bo
• @MessageBundle must be declared on an interface: {bundleClas

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