{"record":{"id":"9e49b62d64e80c0f","repo":"quarkusio/quarkus","slug":"the-class-name-cannot-be-created-during-deplo","errorCode":null,"errorMessage":"The class (${name}) cannot be created during deployment.","messagePattern":"The class \\((.+?)\\) cannot be created during deployment\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"core/deployment/src/main/java/io/quarkus/deployment/builditem/GeneratedConfigClassBuildItem.java","lineNumber":76,"sourceCode":"        boolean isApplicationClass = QuarkusClassLoader.isApplicationClass(configClass.getName());\n\n        Map<Class<?>, ConfigClassImplementation> elements = new HashMap<>();\n        Set<DotName> interfaces = new HashSet<>();\n        Set<DotName> implementations = new HashSet<>();\n        for (ConfigMappingMetadata metadata : configMappingsMetadata) {\n            elements.putIfAbsent(metadata.getInterfaceType(), new ConfigClassImplementation(metadata, isApplicationClass));\n            interfaces.add(DotName.createSimple(metadata.getInterfaceType()));\n            implementations.add(DotName.createSimple(metadata.getClassName()));\n        }\n        return new GeneratedConfigClassBuildItem(configClass, elements, interfaces, implementations);\n    }\n\n    private static Class<?> loadClass(final String name) {\n        ClassLoader classLoader = Thread.currentThread().getContextClassLoader();\n        try {\n            return classLoader.loadClass(name);\n        } catch (ClassNotFoundException e) {\n            throw new IllegalStateException(\"The class (\" + name + \") cannot be created during deployment.\", e);\n        }\n    }\n\n    @Override\n    public boolean equals(final Object o) {\n        if (this == o) {\n            return true;\n        }\n        if (o == null || getClass() != o.getClass()) {\n            return false;\n        }\n        final GeneratedConfigClassBuildItem that = (GeneratedConfigClassBuildItem) o;\n        return configClass.equals(that.configClass);\n    }\n\n    @Override\n    public int hashCode() {\n        return configClass.hashCode();","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/core/deployment/src/main/java/io/quarkus/deployment/builditem/GeneratedConfigClassBuildItem.java#L58-L94","documentation":"GeneratedConfigClassBuildItem.of() tries to load an already-generated configuration class via the current thread's context classloader during deployment. If the class cannot be found, it cannot be created during deployment and the method throws this IllegalStateException wrapping the ClassNotFoundException. It usually means the class was never generated, was not on the deployment classpath, or the wrong (unqualified/wrong-loader) name was passed.","triggerScenarios":"Calling GeneratedConfigClassBuildItem.of(name) where the context classloader cannot load `name` — the generated config class is missing from the augmentor's classloader or the name doesn't match the generated FQN.","commonSituations":"Extension build steps referencing a config class before the step that generates it runs; classloader isolation in tests or custom runners where generated classes aren't visible; typos/mismatched fully-qualified names.","solutions":["Verify the build step that generates the config class runs before the step calling of() — check @BuildStep ordering/dependencies (produces/consumes).","Confirm the exact fully-qualified class name matches what the generator produced (package + name, inner-class separators as $).","Run a clean build (./mvnw clean install) to discard stale incremental state, and check that the context classloader is the Quarkus augmentor CL, not a test/IDE classloader."],"exampleFix":"// before: runs too early, class not yet generated\n@BuildStep\nvoid useConfig(BuildProducer<GeneratedConfigClassBuildItem> out) {\n    Class<?> c = GeneratedConfigClassBuildItem.of(\"com.acme.MyConfig\");\n}\n// after: order via build items\n@BuildStep\nvoid useConfig(GeneratedConfigClassBuildItem generatedConfig) {\n    // consume the produced item instead of loading by name prematurely\n}","handlingStrategy":"validation","validationCode":"Class<?> tryLoad(String name) {\n    ClassLoader cl = Thread.currentThread().getContextClassLoader();\n    try { return cl.loadClass(name); } catch (ClassNotFoundException e) { return null; }\n}\n// call of() only when tryLoad(...) != null","typeGuard":null,"tryCatchPattern":"try {\n    Class<?> c = GeneratedConfigClassBuildItem.of(name);\n} catch (IllegalStateException e) {\n    if (e.getCause() instanceof ClassNotFoundException) {\n        throw new IllegalStateException(\"Config class \" + name + \" was not generated yet; check @BuildStep ordering\", e);\n    }\n    throw e;\n}","preventionTips":["Ensure the generating @BuildStep runs before steps that call of() (use produced BuildItem as an argument to enforce order)","Use the exact generated FQN; build it from a shared constant rather than hardcoding strings","Clean-build when switching branches; stale incremental state can hide generated classes","Log/verify the context classloader in build steps that load generated classes"],"tags":["quarkus","classloading","config-generation","build-time"],"backgroundTag":"classnotfound-during-deployment","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"}