{"record":{"id":"f4c8eb46eff64376","repo":"quarkusio/quarkus","slug":"the-class-name-cannot-be-created-during-deplo-f4c8eb","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/steps/ConfigGenerationBuildStep.java","lineNumber":1226,"sourceCode":"        if (configMappings.isEmpty()) {\n            return Collections.emptySet();\n        }\n\n        Set<ConfigClass> configClasses = new HashSet<>();\n        for (Entry<String, Set<String>> entry : configMappings.get().getConfigMappings().entrySet()) {\n            for (String prefix : entry.getValue()) {\n                configClasses.add(ConfigClass.configClass(loadClass(entry.getKey()), prefix));\n            }\n        }\n        return configClasses;\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    private static Type getConverterType(final ClassInfo converter, final CombinedIndexBuildItem combinedIndex) {\n        if (converter.name().toString().equals(Object.class.getName())) {\n            throw new IllegalArgumentException(\n                    \"Can not add converter \" + converter.name() + \" that is not parameterized with a type\");\n        }\n\n        for (Type type : converter.interfaceTypes()) {\n            if (type instanceof ParameterizedType) {\n                ParameterizedType parameterizedType = type.asParameterizedType();\n                if (parameterizedType.name().equals(CONVERTER_NAME)) {\n                    List<Type> arguments = parameterizedType.arguments();\n                    if (arguments.size() != 1) {\n                        throw new IllegalArgumentException(\n                                \"Converter \" + converter.name() + \" must be parameterized with a single type\");\n                    }","sourceCodeStart":1208,"sourceCodeEnd":1244,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/core/deployment/src/main/java/io/quarkus/deployment/steps/ConfigGenerationBuildStep.java#L1208-L1244","documentation":"ConfigGenerationBuildStep resolves custom converter classes declared via @ConfigMapping converters or config.converter-class configuration. loadClass attempts to load the named class with the thread context classloader during deployment; if the class is not on the deployment classpath an IllegalStateException is thrown naming the class.","triggerScenarios":"A converter class name registered through quarkus.smallrye.config.converter-class (or an extension-supplied converter reference) points to a class that cannot be loaded by the deployment classloader at build time.","commonSituations":"Typo in the fully qualified class name; converter class lives in a test or provided-scope dependency not visible at deployment; converter defined in an application module excluded from augmentation; refactoring/renaming the converter package without updating the config property.","solutions":["Fix the fully qualified class name so it matches the actual converter class","Add the module/jar containing the converter to the application's compile/runtime dependencies","Check the package was not renamed — update the converter registration accordingly","Implement the converter as a class inside the application itself (smallrye.config.Converter implementation) rather than referencing an external class"],"exampleFix":"// before\nquarkus.smallrye.config.converter-class=com.acme.old.ColorConverter\n// after\nquarkus.smallrye.config.converter-class=com.acme.config.ColorConverter","handlingStrategy":"validation","validationCode":"String name = \"com.acme.config.ColorConverter\";\ntry {\n    Class.forName(name, false, Thread.currentThread().getContextClassLoader());\n} catch (ClassNotFoundException e) {\n    throw new IllegalStateException(\"Converter class not on deployment classpath: \" + name);\n}","typeGuard":null,"tryCatchPattern":"try {\n    quarkusBuild();\n} catch (IllegalStateException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"cannot be created during deployment\")) {\n        // fix the converter class name / add its jar to dependencies\n    }\n    throw e;\n}","preventionTips":["Always use the fully qualified class name for converter registration","Keep converters in application (compile-scope) modules, not test or provided scope","Re-check converter registrations after any package refactor","Prefer registering converters as beans/classes in the app over referencing external class names"],"tags":["quarkus","config","classpath","classloading"],"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-14T00:17:10.932Z"}