{"record":{"id":"c7f4a4749f20f9a4","repo":"quarkusio/quarkus","slug":"unable-to-preload-class-pre-init-instructions-n","errorCode":null,"errorMessage":"Unable to preload class: . Pre-init instructions need to be adjusted.","messagePattern":"Unable to preload class: \\. Pre-init instructions need to be adjusted\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"core/runtime/src/main/java/io/quarkus/runtime/init/InitializeClassPreInitRunnable.java","lineNumber":20,"sourceCode":"\npublic class InitializeClassPreInitRunnable implements Runnable {\n\n    private static final boolean PRE_INIT_RAISE_ERRORS = Boolean.getBoolean(\"quarkus-pre-init-raise-errors\");\n\n    private final String className;\n\n    public InitializeClassPreInitRunnable(String className) {\n        this.className = className;\n    }\n\n    @Override\n    public void run() {\n        try {\n            Class.forName(className, true, Thread.currentThread().getContextClassLoader());\n        } catch (Throwable e) {\n            // when testing Quarkus itself, we raise the errors, so that we can catch them\n            if (PRE_INIT_RAISE_ERRORS) {\n                throw new IllegalStateException(\n                        \"Unable to preload class: \" + className + \". Pre-init instructions need to be adjusted.\", e);\n            }\n\n            // otherwise we simply ignore the errors\n        }\n    }\n}\n","sourceCodeStart":2,"sourceCodeEnd":28,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/core/runtime/src/main/java/io/quarkus/runtime/init/InitializeClassPreInitRunnable.java#L2-L28","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Correct the pre-init configuration: remove or fix the class name entry that fails to load","Verify the class and its static-initializer dependencies are on the classpath at pre-init time","Adjust pre-init instructions (RunTimeInitialization/graalvm config) so the class is initialized at runtime instead","If the class' initialization is not build-time safe, exclude it from pre-init"],"exampleFix":"// before (pre-init config): com.example.NurvClass listed but renamed\n// after: update entry\n\"io.quarkus.runtime.graal.PreInit\": { \"className\": \"com.example.NewClassName\" }","handlingStrategy":"validation","validationCode":"// before adding a class to pre-init, verify it loads with no side effects\nClass.forName(\"com.example.TargetClass\", true, getClass().getClassLoader()); // must not throw","typeGuard":null,"tryCatchPattern":"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; }","preventionTips":["Only list classes with side-effect-free static initializers for pre-init","Update pre-init entries when refactoring class names","Test native builds after changing pre-init configuration"],"tags":["native-image","pre-init","classloading"],"backgroundTag":"pre-init-class-load-failed","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}