{"record":{"id":"16c9611725c2e041","repo":"quarkusio/quarkus","slug":"unable-to-instantiate-sectionhelperfactory-engin","errorCode":null,"errorMessage":"Unable to instantiate SectionHelperFactory: <engineConfigClass>","messagePattern":"Unable to instantiate SectionHelperFactory: <engineConfigClass>","errorType":"exception","errorClass":"java.lang.IllegalStateException","httpStatus":null,"severity":"error","filePath":"extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/QuteProcessor.java","lineNumber":693,"sourceCode":"            }\n        }\n\n        // Register additional section factories and parser hooks\n        if (engineConfigurations.isPresent()) {\n            // Use the deployment class loader - it can load application classes; it's non-persistent and isolated\n            ClassLoader tccl = Thread.currentThread().getContextClassLoader();\n            IndexView index = beanArchiveIndex.getIndex();\n\n            for (ClassInfo engineConfigClass : engineConfigurations.get().getConfigurations()) {\n                if (Types.isImplementorOf(engineConfigClass, Names.SECTION_HELPER_FACTORY, index)) {\n                    try {\n                        Class<?> sectionHelperFactoryClass = tccl.loadClass(engineConfigClass.toString());\n                        SectionHelperFactory<?> factory = (SectionHelperFactory<?>) sectionHelperFactoryClass\n                                .getDeclaredConstructor().newInstance();\n                        builder.addSectionHelper(factory);\n                        LOGGER.debugf(\"SectionHelperFactory registered during template analysis: %s\", engineConfigClass);\n                    } catch (Exception e) {\n                        throw new IllegalStateException(\"Unable to instantiate SectionHelperFactory: \" + engineConfigClass, e);\n                    }\n                } else if (Types.isImplementorOf(engineConfigClass, Names.PARSER_HOOK, index)) {\n                    try {\n                        Class<?> parserHookClass = tccl.loadClass(engineConfigClass.toString());\n                        ParserHook parserHook = (ParserHook) parserHookClass.getDeclaredConstructor().newInstance();\n                        builder.addParserHook(parserHook);\n                        LOGGER.debugf(\"ParserHook registered during template analysis: %s\", engineConfigClass);\n                    } catch (Exception e) {\n                        throw new IllegalStateException(\"Unable to instantiate ParserHook: \" + engineConfigClass, e);\n                    }\n                }\n            }\n        }\n\n        builder.computeSectionHelper(name -> {\n            // Create a dummy section helper factory for an unknown section that could be potentially registered at runtime\n            return new SectionHelperFactory<SectionHelper>() {\n                @Override","sourceCodeStart":675,"sourceCodeEnd":711,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/qute/deployment/src/main/java/io/quarkus/qute/deployment/QuteProcessor.java#L675-L711","documentation":"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.","triggerScenarios":"analyzeTemplates iterates engine-config classes; a class implementing SectionHelperFactory is loaded with tccl.loadClass() and getDeclaredConstructor().newInstance(); any Exception (ClassNotFoundException, InstantiationException, InvocationTargetException) is wrapped.","commonSituations":"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.","solutions":["Give the factory a public no-arg constructor and ensure its constructor/static init does not throw","Check the wrapped 'Caused by' in the stack trace for the real failure (ClassNotFound vs InvocationTargetException)","Make sure the factory class lives in a runtime module of the same Quarkus/Qute version and is on the application classpath","If the class is not a factory, fix the engine configuration registration that lists it"],"exampleFix":"// before\npublic class MyFactory implements SectionHelperFactory<MyHelper> {\n    public MyFactory(String bad) { ... } // no no-arg ctor\n}\n// after\npublic class MyFactory implements SectionHelperFactory<MyHelper> {\n    public MyFactory() { }\n}","handlingStrategy":"validation","validationCode":"// verify the factory can be instantiated before the build\nClass<?> c = Class.forName(\"com.acme.MySectionFactory\", true, Thread.currentThread().getContextClassLoader());\nif (!SectionHelperFactory.class.isAssignableFrom(c)) throw new IllegalStateException(\"Not a factory\");\nc.getDeclaredConstructor().setAccessible(true);\nObject f = c.getDeclaredConstructor().newInstance(); // fails early with clear cause","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Always provide a public no-arg constructor on SectionHelperFactory implementations","Keep factory constructors side-effect free","Match Qute/Quarkus versions between runtime and deployment modules","Read the 'Caused by' chain — it names the real instantiation failure"],"tags":["qute","build-time","reflection","section-helper"],"backgroundTag":"class-instantiation-failed","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}