quarkusio/quarkus · error · IOException

Cannot find ClassLoadingRecorder.class on classpath

Error message

Cannot find ClassLoadingRecorder.class on classpath

What it means

ForkedJvmEnvironment.writeRecorderClass copies ClassLoadingRecorder.class (and its nested $RecordingClassLoader.class) from the deployment classloader into the temp dir used to boot a forked JVM. If the base .class resource cannot be found on the classpath, this IOException is thrown, meaning the forked environment cannot be set up.

Source

Thrown at core/deployment/src/main/java/io/quarkus/deployment/pkg/steps/ForkedJvmEnvironment.java:181

            }
            String classFile = entry.getKey().replace('.', '/') + ".class";
            Path target = dir.resolve(classFile);
            Files.createDirectories(target.getParent());
            Files.write(target, bytes);
        }
    }

    /**
     * Writes the {@link ClassLoadingRecorder} class files to the temp directory.
     */
    private static void writeRecorderClass(Path tempDir) throws IOException {
        String baseName = ClassLoadingRecorder.class.getName().replace('.', '/');
        for (String suffix : new String[] { ".class", "$RecordingClassLoader.class" }) {
            String resourcePath = baseName + suffix;
            try (var is = ForkedJvmEnvironment.class.getClassLoader().getResourceAsStream(resourcePath)) {
                if (is == null) {
                    if (suffix.equals(".class")) {
                        throw new IOException("Cannot find ClassLoadingRecorder.class on classpath");
                    }
                    continue;
                }
                Path target = tempDir.resolve(resourcePath);
                Files.createDirectories(target.getParent());
                Files.write(target, is.readAllBytes());
            }
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Rebuild with a clean local repository: mvn clean and remove ~/.m2 stale quarkus artifacts.
2. Verify quarkus-deployment jar is intact and contains io/quarkus/deployment/pkg/steps/ClassLoadingRecorder.class (jar tf).
3. Disable custom shading/relocation/proguard plugins that strip quarkus-deployment resources.
4. Check for custom classloader configuration (e.g. security policies or classpath filters) blocking getResourceAsStream.
5. Reproduce with the standard build (plain mvn package) to rule out environment-specific classloading.

String res = "io/quarkus/deployment/pkg/steps/ClassLoadingRecorder.class";
if (Thread.currentThread().getContextClassLoader().getResource(res) == null
        && ForkedJvmEnvironment.class.getClassLoader().getResource(res) == null) {
    throw new IllegalStateException("quarkus-deployment jar missing/corrupt: " + res
            + " — run 'mvn clean' and re-download dependencies");
}

When it happens

Trigger: create() prepares a forked JVM (e.g. for CDS/AppCDS or JVM startup optimization) and ClassLoadingRecorder.class is missing from the classloader's resources — typically the deployment classes are not packaged in the expected location, or a shading/relocation/shrink step removed it.

Common situations: Running Quarkus built from an unusual/unofficial distribution; custom classloading setups (security managers, isolated classloaders, Gradle/Maven classpath filtering); relocation/shading plugins stripping io.quarkus.deployment resources; truncated or partially extracted quarkus-deployment jar.

Related errors

• Failed to load steps from %s
• The class (${name}) cannot be created during deployment.
• Failed to load the condition class ${testClassName} for capa
• The class (${name}) cannot be created during deployment.
• Unable to find main method on class '${originalMainClassName

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