quarkusio/quarkus · critical · RuntimeException

Failed to load steps from %s

Error message

Failed to load steps from %s

What it means

RuntimeException thrown by ExtensionLoader.loadStepsFrom when loading build step classes listed in META-INF/quarkus-build-steps.list fails: ExtensionLoader.loadStepsFromClass(clazz) threw any Throwable. This happens while assembling the extension's build steps during deployment processing — a broken build-step class (missing methods, linkage errors, exception in static init/annotation processing) aborts the Quarkus augmentation.

Source

Thrown at core/deployment/src/main/java/io/quarkus/deployment/ExtensionLoader.java:160

        // BooleanSupplier factory
        result = result.andThen(bcb -> bcb.addBuildStep(new io.quarkus.builder.BuildStep() {

            @Override
            public void execute(BuildContext context) {
                context.produce(bsf);
            }

            @Override
            public String getId() {
                return ExtensionLoader.class.getName() + "#booleanSupplierFactory";
            }
        }).produces(BooleanSupplierFactoryBuildItem.class).build());

        for (Class<?> clazz : ServiceUtil.classesNamedIn(classLoader, "META-INF/quarkus-build-steps.list")) {
            try {
                result = result.andThen(ExtensionLoader.loadStepsFromClass(clazz, bsf));
            } catch (Throwable e) {
                throw new RuntimeException("Failed to load steps from " + clazz, e);
            }
        }

        result = result.andThen(bcb -> bcb.addBuildStep(new io.quarkus.builder.BuildStep() {

            @Override
            public void execute(BuildContext bc) {
                bc.produce(new ConfigurationBuildItem(readResult));

                ObjectLoader valueRegistryLoader = new ObjectLoader() {
                    @Override
                    public ResultHandle load(BytecodeCreator body, Object obj, Class<?> type, boolean staticInit) {
                        // What we get here is the body of io.quarkus.runtime.StartupTask.deploy method
                        // with StartupContext, but is it always like this?
                        MethodCreator methodCreator = (MethodCreator) body;
                        MethodDescriptor getValue = MethodDescriptor.ofMethod(StartupContext.class, "getValue", Object.class,
                                String.class);

View on GitHub (pinned to e1c734241f)

Solutions

1. Align all Quarkus extensions to one BOM/version (mvn dependency:tree to find mismatches) and rebuild
2. Run a clean build to flush stale augmentation state after a Quarkus upgrade
3. Inspect the 'Caused by' for NoClassDefFoundError/NoSuchMethodError and add/fix the missing dependency
4. If you author the extension, ensure build-step classes only reference classes available in the deployment module

Example fix

// before: mixed versions in pom.xml
<quarkus.platform.version>3.14.0</quarkus.platform.version>
<quarkus.extension.version>2.16.0.Final</quarkus.extension.version>
// after: single platform import
<dependency>
  <groupId>io.quarkus.platform</groupId>
  <artifactId>quarkus-bom</artifactId>
  <version>3.14.0</version>
  <type>pom</type>
</dependency>

// Detect version drift among Quarkus artifacts before building
mvn dependency:tree -Dincludes=io.quarkus,io.quarkiverse.* | grep quarkus
// All io.quarkus artifacts must share one version; fail if not

for (Class<?> clazz : ServiceUtil.classesNamedIn(classLoader, "META-INF/quarkus-build-steps.list")) {
    try {
        result = result.andThen(ExtensionLoader.loadStepsFromClass(clazz, bsf));
    } catch (Throwable e) {
        Throwable r = e;
        while (r.getCause() != null) r = r.getCause();
        throw new IllegalStateException("Fix extension version/classpath for " + clazz.getName() + ": " + r, e);
    }
}

When it happens

Trigger: loadStepsFrom iterates classesNamedIn(classLoader, "META-INF/quarkus-build-steps.list") and calls loadStepsFromClass for each; a NoClassDefFoundError for a type referenced by a build-step method, NoSuchMethodError from mismatched extension versions, or any exception during method scanning produces 'Failed to load steps from <clazz>'.

Common situations: Mixed Quarkus extension versions on the build classpath (BOM mismatch); an extension deployment jar compiled against a different Quarkus core version; a build step referencing classes not on the deployment classpath (classloading violation); stale incremental-build state after a Quarkus upgrade.

Related errors

• A build step must be a non-static method: %s
• The class (${name}) cannot be created during deployment.
• The class (${name}) cannot be created during deployment.
• Unable to find main method on class '${originalMainClassName
• Unknown class: ${token}

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