quarkusio/quarkus · error · ClassLoadingException

Unable to load class [<className>]

Error message

Unable to load class [<className>]

What it means

FlatClassLoaderService is Hibernate ORM's class-loading bridge to Quarkus' flat (single) classloader. classForName wraps any ClassNotFoundException/LinkageError from Class.forName into Hibernate's ClassLoadingException with this message. It means Hibernate was asked to instantiate or load a class by name that isn't visible in the application archive.

Source

Thrown at extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/service/FlatClassLoaderService.java:37

/**
 * Replaces the ClassLoaderService in Hibernate ORM with one which should work in native mode.
 */
public class FlatClassLoaderService implements ClassLoaderService {

    private static final BootLogging log = BootLogging.BOOT_LOGGER;
    public static final ClassLoaderService INSTANCE = new FlatClassLoaderService();

    private FlatClassLoaderService() {
        // use #INSTANCE when you need one
    }

    @SuppressWarnings("unchecked")
    @Override
    public <T> Class<T> classForName(String className) {
        try {
            return (Class<T>) Class.forName(className, false, getClassLoader());
        } catch (Exception | LinkageError e) {
            throw new ClassLoadingException("Unable to load class [" + className + "]", e);
        }
    }

    @Override
    public URL locateResource(String name) {
        URL resource = getClassLoader().getResource(name);
        if (resource == null) {
            log.debugf(
                    "Loading of resource '%s' failed. Maybe that's ok, maybe you forgot to include this resource in the binary image? -H:IncludeResources=",
                    name);
        } else {
            log.tracef("Successfully loaded resource '%s'", name);
        }
        return resource;
    }

    @Override
    public InputStream locateResourceStream(String name) {

View on GitHub (pinned to e1c734241f)

Solutions

1. Check the class name in the message for typos and verify the fully-qualified name (package included).
2. Add the dependency containing the class to the application (Maven/Gradle), so it lands in the Quarkus archive.
3. In native builds, register the class for reflection (or ensure the relevant Quarkus extension handles it) so it isn't eliminated.
4. Prefer letting Quarkus auto-detect the dialect (remove explicit dialect settings) instead of naming classes in config.

Example fix

// before
quarkus.hibernate-orm.dialect=org.hibernate.dialect.PostgreSQL95Dialect // typo/removed class

// after
# let Quarkus detect it, or use a valid value
quarkus.hibernate-orm.dialect=org.hibernate.dialect.PostgreSQLDialect

// Verify the class is loadable before configuring Hibernate with it
try {
    Class.forName("com.example.MyType", false,
        Thread.currentThread().getContextClassLoader());
} catch (ClassNotFoundException | LinkageError e) {
    throw new IllegalStateException("Class not on application classpath: " + e.getMessage());
}

try {
    entityManager.find(Entity.class, id);
} catch (ClassLoadingException e) {
    log.error("Hibernate could not load a class: {} — check spelling and dependencies", e.getMessage());
    throw e;
}

When it happens

Trigger: Hibernate resolving classes by string name (dialects, type classes, entity listeners, converters, interceptors, `hibernate.query.*` classes, custom UserTypes) where the class name is misspelled, the class isn't in the application, or the class was excluded from native compilation.

Common situations: Typos in config properties like hibernate.dialect or custom type mappings; referencing classes from a library not included as a dependency; @Converter/listener classes registered by name from an external jar; GraalVM native-image excluding a reflectively-accessed class.

Related errors

• Unable to preload class: . Pre-init instructions need to be
• Unable to find handleRequest method in <handlerClass.getName
• Unable to create new instance for ${clazz}
• Failed to read class bytes for '${className}', class not pre
• Persistence providers are not available during the static in

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