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

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.

Source

Thrown at core/deployment/src/main/java/io/quarkus/deployment/builditem/GeneratedConfigClassBuildItem.java:76

        boolean isApplicationClass = QuarkusClassLoader.isApplicationClass(configClass.getName());

        Map<Class<?>, ConfigClassImplementation> elements = new HashMap<>();
        Set<DotName> interfaces = new HashSet<>();
        Set<DotName> implementations = new HashSet<>();
        for (ConfigMappingMetadata metadata : configMappingsMetadata) {
            elements.putIfAbsent(metadata.getInterfaceType(), new ConfigClassImplementation(metadata, isApplicationClass));
            interfaces.add(DotName.createSimple(metadata.getInterfaceType()));
            implementations.add(DotName.createSimple(metadata.getClassName()));
        }
        return new GeneratedConfigClassBuildItem(configClass, elements, interfaces, implementations);
    }

    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);
        }
    }

    @Override
    public boolean equals(final Object o) {
        if (this == o) {
            return true;
        }
        if (o == null || getClass() != o.getClass()) {
            return false;
        }
        final GeneratedConfigClassBuildItem that = (GeneratedConfigClassBuildItem) o;
        return configClass.equals(that.configClass);
    }

    @Override
    public int hashCode() {
        return configClass.hashCode();

View on GitHub (pinned to e1c734241f)

Solutions

1. Verify the build step that generates the config class runs before the step calling of() — check @BuildStep ordering/dependencies (produces/consumes).
2. Confirm the exact fully-qualified class name matches what the generator produced (package + name, inner-class separators as $).
3. 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.

Example fix

// before: runs too early, class not yet generated
@BuildStep
void useConfig(BuildProducer<GeneratedConfigClassBuildItem> out) {
    Class<?> c = GeneratedConfigClassBuildItem.of("com.acme.MyConfig");
}
// after: order via build items
@BuildStep
void useConfig(GeneratedConfigClassBuildItem generatedConfig) {
    // consume the produced item instead of loading by name prematurely
}

Class<?> tryLoad(String name) {
    ClassLoader cl = Thread.currentThread().getContextClassLoader();
    try { return cl.loadClass(name); } catch (ClassNotFoundException e) { return null; }
}
// call of() only when tryLoad(...) != null

try {
    Class<?> c = GeneratedConfigClassBuildItem.of(name);
} catch (IllegalStateException e) {
    if (e.getCause() instanceof ClassNotFoundException) {
        throw new IllegalStateException("Config class " + name + " was not generated yet; check @BuildStep ordering", e);
    }
    throw e;
}

When it happens

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

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

Related errors

• Failed to open path tree with root %s
• Failed to load steps from %s
• Dev services for ${request.getName()} requires a startable s
• Name cannot start with '/':${name}
• Use GeneratedServiceProviderBuildItem to register service pr

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