quarkusio/quarkus · error · IllegalStateException

The class (${name}) cannot be created during deployment.

Error message

The class (${name}) cannot be created during deployment.

What it means

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.

Source

Thrown at core/deployment/src/main/java/io/quarkus/deployment/steps/ConfigGenerationBuildStep.java:1226

        if (configMappings.isEmpty()) {
            return Collections.emptySet();
        }

        Set<ConfigClass> configClasses = new HashSet<>();
        for (Entry<String, Set<String>> entry : configMappings.get().getConfigMappings().entrySet()) {
            for (String prefix : entry.getValue()) {
                configClasses.add(ConfigClass.configClass(loadClass(entry.getKey()), prefix));
            }
        }
        return configClasses;
    }

    private static Class<?> loadClass(final String name) {
        ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
        try {
            return classLoader.loadClass(name);
        } catch (ClassNotFoundException e) {
            throw new IllegalStateException("The class (" + name + ") cannot be created during deployment.", e);
        }
    }

    private static Type getConverterType(final ClassInfo converter, final CombinedIndexBuildItem combinedIndex) {
        if (converter.name().toString().equals(Object.class.getName())) {
            throw new IllegalArgumentException(
                    "Can not add converter " + converter.name() + " that is not parameterized with a type");
        }

        for (Type type : converter.interfaceTypes()) {
            if (type instanceof ParameterizedType) {
                ParameterizedType parameterizedType = type.asParameterizedType();
                if (parameterizedType.name().equals(CONVERTER_NAME)) {
                    List<Type> arguments = parameterizedType.arguments();
                    if (arguments.size() != 1) {
                        throw new IllegalArgumentException(
                                "Converter " + converter.name() + " must be parameterized with a single type");
                    }

View on GitHub (pinned to e1c734241f)

Solutions

1. Fix the fully qualified class name so it matches the actual converter class
2. Add the module/jar containing the converter to the application's compile/runtime dependencies
3. Check the package was not renamed — update the converter registration accordingly
4. Implement the converter as a class inside the application itself (smallrye.config.Converter implementation) rather than referencing an external class

Example fix

// before
quarkus.smallrye.config.converter-class=com.acme.old.ColorConverter
// after
quarkus.smallrye.config.converter-class=com.acme.config.ColorConverter

String name = "com.acme.config.ColorConverter";
try {
    Class.forName(name, false, Thread.currentThread().getContextClassLoader());
} catch (ClassNotFoundException e) {
    throw new IllegalStateException("Converter class not on deployment classpath: " + name);
}

try {
    quarkusBuild();
} catch (IllegalStateException e) {
    if (e.getMessage() != null && e.getMessage().contains("cannot be created during deployment")) {
        // fix the converter class name / add its jar to dependencies
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unknown class: ${token}
• Unable to load the config property type: ${className}
• Unable to load repository/entity class mapping ->
• Unable to load class '{className}' for supporting custom JSO
• Failed to load CodeGenProvider class from deployment classlo

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