quarkusio/quarkus · error · IllegalStateException

Unable to preload class: . Pre-init instructions need to be

Error message

Unable to preload class: . Pre-init instructions need to be adjusted.

What it means

Quarkus pre-initializes selected classes at build time via InitializeClassPreInitRunnable; if Class.forName fails to load/pre-init a class it throws IllegalStateException (in Quarkus' own test builds, flagged by PRE_INIT_RAISE_ERRORS) saying pre-init instructions need adjustment. Note the message shows an empty class name because the className string is concatenated from a blank value in this run. It signals that a class listed for pre-init cannot actually be loaded in the pre-init environment.

Source

Thrown at core/runtime/src/main/java/io/quarkus/runtime/init/InitializeClassPreInitRunnable.java:20

public class InitializeClassPreInitRunnable implements Runnable {

    private static final boolean PRE_INIT_RAISE_ERRORS = Boolean.getBoolean("quarkus-pre-init-raise-errors");

    private final String className;

    public InitializeClassPreInitRunnable(String className) {
        this.className = className;
    }

    @Override
    public void run() {
        try {
            Class.forName(className, true, Thread.currentThread().getContextClassLoader());
        } catch (Throwable e) {
            // when testing Quarkus itself, we raise the errors, so that we can catch them
            if (PRE_INIT_RAISE_ERRORS) {
                throw new IllegalStateException(
                        "Unable to preload class: " + className + ". Pre-init instructions need to be adjusted.", e);
            }

            // otherwise we simply ignore the errors
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Correct the pre-init configuration: remove or fix the class name entry that fails to load
2. Verify the class and its static-initializer dependencies are on the classpath at pre-init time
3. Adjust pre-init instructions (RunTimeInitialization/graalvm config) so the class is initialized at runtime instead
4. If the class' initialization is not build-time safe, exclude it from pre-init

Example fix

// before (pre-init config): com.example.NurvClass listed but renamed
// after: update entry
"io.quarkus.runtime.graal.PreInit": { "className": "com.example.NewClassName" }

// before adding a class to pre-init, verify it loads with no side effects
Class.forName("com.example.TargetClass", true, getClass().getClassLoader()); // must not throw

try { preInitClass(name); } catch (IllegalStateException e) { if (e.getMessage().startsWith("Unable to preload class")) log.warn("Pre-init failed for class, deferring to runtime init"); else throw e; }

When it happens

Trigger: Running Quarkus' own test suite where PRE_INIT_RAISE_ERRORS is true, and a class registered for pre-init (via pre-init configuration/RunTimeInitialization) fails Class.forName — missing dependency, wrong class name, or class loading triggers unsupported native setup.

Common situations: Contributing a new class to Quarkus' pre-init list; a dependency change moved/renamed a pre-initialized class; class' static initializer depends on runtime-only state.

Related errors

• Unable to load class [<className>]
• Failed to load steps from %s
• The class (${name}) cannot be created during deployment.
• service interface name cannot be null or blank
• service interface descriptor file path cannot be null

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