{"record":{"id":"a92264bd1645fb96","repo":"quarkusio/quarkus","slug":"unable-to-load-class-classname","errorCode":null,"errorMessage":"Unable to load class [<className>]","messagePattern":"Unable to load class \\[<className>\\]","errorType":"exception","errorClass":"ClassLoadingException","httpStatus":null,"severity":"error","filePath":"extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/service/FlatClassLoaderService.java","lineNumber":37,"sourceCode":"/**\n * Replaces the ClassLoaderService in Hibernate ORM with one which should work in native mode.\n */\npublic class FlatClassLoaderService implements ClassLoaderService {\n\n    private static final BootLogging log = BootLogging.BOOT_LOGGER;\n    public static final ClassLoaderService INSTANCE = new FlatClassLoaderService();\n\n    private FlatClassLoaderService() {\n        // use #INSTANCE when you need one\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    @Override\n    public <T> Class<T> classForName(String className) {\n        try {\n            return (Class<T>) Class.forName(className, false, getClassLoader());\n        } catch (Exception | LinkageError e) {\n            throw new ClassLoadingException(\"Unable to load class [\" + className + \"]\", e);\n        }\n    }\n\n    @Override\n    public URL locateResource(String name) {\n        URL resource = getClassLoader().getResource(name);\n        if (resource == null) {\n            log.debugf(\n                    \"Loading of resource '%s' failed. Maybe that's ok, maybe you forgot to include this resource in the binary image? -H:IncludeResources=\",\n                    name);\n        } else {\n            log.tracef(\"Successfully loaded resource '%s'\", name);\n        }\n        return resource;\n    }\n\n    @Override\n    public InputStream locateResourceStream(String name) {","sourceCodeStart":19,"sourceCodeEnd":55,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/service/FlatClassLoaderService.java#L19-L55","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Check the class name in the message for typos and verify the fully-qualified name (package included).","Add the dependency containing the class to the application (Maven/Gradle), so it lands in the Quarkus archive.","In native builds, register the class for reflection (or ensure the relevant Quarkus extension handles it) so it isn't eliminated.","Prefer letting Quarkus auto-detect the dialect (remove explicit dialect settings) instead of naming classes in config."],"exampleFix":"// before\nquarkus.hibernate-orm.dialect=org.hibernate.dialect.PostgreSQL95Dialect // typo/removed class\n\n// after\n# let Quarkus detect it, or use a valid value\nquarkus.hibernate-orm.dialect=org.hibernate.dialect.PostgreSQLDialect","handlingStrategy":"validation","validationCode":"// Verify the class is loadable before configuring Hibernate with it\ntry {\n    Class.forName(\"com.example.MyType\", false,\n        Thread.currentThread().getContextClassLoader());\n} catch (ClassNotFoundException | LinkageError e) {\n    throw new IllegalStateException(\"Class not on application classpath: \" + e.getMessage());\n}","typeGuard":null,"tryCatchPattern":"try {\n    entityManager.find(Entity.class, id);\n} catch (ClassLoadingException e) {\n    log.error(\"Hibernate could not load a class: {} — check spelling and dependencies\", e.getMessage());\n    throw e;\n}","preventionTips":["Double-check fully-qualified class names in Hibernate config properties","Let Quarkus auto-detect dialects instead of naming dialect classes","In native builds, verify reflectively-used classes are registered (extensions usually do this)","Ensure the jar containing custom types/listeners is an application dependency"],"tags":["hibernate-orm","classloading","native-image","reflection"],"backgroundTag":"classnotfound","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}