oracle/graal · error · ClassNotFoundException

%s (class loading not supported in libgraal)

Error message

%s (class loading not supported in libgraal)

What it means

Error "%s (class loading not supported in libgraal)" thrown in oracle/graal.

Source

Thrown at compiler/src/jdk.graal.compiler.libgraal/src/jdk/graal/compiler/libgraal/LibGraalSubstitutions.java:89

        /**
         * Make package-private {@code clean()} accessible so that it can be called from
         * {@link LibGraalSupportImpl#doReferenceHandling()}.
         */
        @Alias
        public static native void clean();
    }

    /// Removes string-based class lookup from the libgraal runtime image. All compiler classes and
    /// providers needed by libgraal are discovered while building the image, and libgraal does not
    /// define or load new Java classes at runtime. Keeping these methods live would make the JDK
    /// class-loading stack reachable, including resource lookup through class loaders, even though
    /// that machinery cannot produce useful results for libgraal.
    @TargetClass(value = java.lang.Class.class, onlyWith = LibGraalFeature.IsEnabled.class)
    static final class Target_java_lang_Class {
        @Substitute
        public static Class<?> forName(String name, boolean initialize, ClassLoader loader)
                        throws ClassNotFoundException {
            throw new ClassNotFoundException(name + " (class loading not supported in libgraal)");
        }

        @Substitute
        private static Class<?> forName(String className, Class<?> caller)
                        throws ClassNotFoundException {
            throw new ClassNotFoundException(className + " (class loading not supported in libgraal)");
        }

        @Substitute
        public static Class<?> forName(Module module, String name) {
            return null;
        }
    }

    /// Cuts off runtime class loading and class-loader resource lookup. Libgraal runs from a closed
    /// image heap with its providers and resources selected during image building, so runtime
    /// classpath probing is dead code. Returning empty results here prevents the normal JDK class
    /// loader implementation from making `URLClassPath`, `FileURLMapper`, jar handling, and jar

View on GitHub (pinned to a66e9ccd1d)

Solutions

1. Fix the condition reported by the error: {} (class loading not supported in libgraal)
2. Check the throwing call site and ensure its documented preconditions (argument values, types, environment, or configuration) are satisfied before the call.

Example fix

Validate inputs and environment so that the failing condition does not occur: {} (class loading not supported in libgraal)

When it happens

Trigger: Thrown at compiler/src/jdk.graal.compiler.libgraal/src/jdk/graal/compiler/libgraal/LibGraalSubstitutions.java:89 when the library encounters an invalid state.

Common situations: Occurs when a caller violates the contract guarded by this check: {} (class loading not supported in libgraal)

AI-assisted analysis of oracle/graal@a66e9ccd1d (2026-08-14). Data as JSON: /api/errors/aff9de1702b44eb3. Report an issue: GitHub.