{"record":{"id":"bda9a1982e210234","repo":"quarkusio/quarkus","slug":"unable-to-load-repository-entity-class-mapping","errorCode":null,"errorMessage":"Unable to load repository/entity class mapping  -> ","messagePattern":"Unable to load repository/entity class mapping  -> ","errorType":"exception","errorClass":"RuntimeException","httpStatus":null,"severity":"error","filePath":"extensions/panache/hibernate-orm-panache-common/runtime/src/main/java/io/quarkus/hibernate/orm/panache/common/runtime/AbstractJpaOperations.java","lineNumber":63,"sourceCode":"        if (entityToPersistenceUnitIsIncomplete == null) {\n            entityToPersistenceUnitIsIncomplete = incomplete;\n        } else {\n            entityToPersistenceUnitIsIncomplete = entityToPersistenceUnitIsIncomplete || incomplete;\n        }\n    }\n\n    private static volatile Map<Class<?>, Class<?>> repositoryClassToEntityClass = Collections.emptyMap();\n\n    public static void setRepositoryClassesToEntityClasses(Map<String, String> map) {\n        Map<Class<?>, Class<?>> converted = new HashMap<>();\n        ClassLoader classLoader = Thread.currentThread().getContextClassLoader();\n        for (Entry<String, String> entry : map.entrySet()) {\n            try {\n                Class<?> repoClass = Class.forName(entry.getKey(), false, classLoader);\n                Class<?> entityClass = Class.forName(entry.getValue(), false, classLoader);\n                converted.put(repoClass, entityClass);\n            } catch (ClassNotFoundException e) {\n                throw new RuntimeException(\"Unable to load repository/entity class mapping \"\n                        + entry.getKey() + \" -> \" + entry.getValue(), e);\n            }\n        }\n        repositoryClassToEntityClass = Collections.unmodifiableMap(converted);\n    }\n\n    public static <Entity> Class<? extends Entity> getRepositoryEntityClass(\n            // FIXME: if we move this to JpaOperations we can add a type constraint on the repo class\n            Class<?> repositoryImplementationClass) {\n        Class<?> ret = repositoryClassToEntityClass.get(repositoryImplementationClass);\n        if (ret == null) {\n            throw new RuntimeException(\"Your repository class \" + repositoryImplementationClass\n                    + \" was not properly detected and assigned an entity type\");\n        }\n        return (Class<? extends Entity>) ret;\n    }\n\n    //","sourceCodeStart":45,"sourceCodeEnd":81,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/panache/hibernate-orm-panache-common/runtime/src/main/java/io/quarkus/hibernate/orm/panache/common/runtime/AbstractJpaOperations.java#L45-L81","documentation":"At startup Panache converts a map of repository-class-name -> entity-class-name (built at augmentation time) into a Class-to-Class map. This error means one of the two class names could not be loaded with the given ClassLoader via Class.forName, i.e. a repository or entity class recorded by the build is missing from the runtime classpath.","triggerScenarios":"Calling setRepositoryClassesToEntityClasses with an entry whose key (repository) or value (entity) names a class not present at runtime — e.g. after removing a dependency or renaming a class while stale augmentation metadata still references it.","commonSituations":"Refactoring a repository/entity package or name without a clean rebuild; excluding classes via Gradle/Maven filtering; quarkus.live-reload inconsistencies; fat-jar built with dependencies excluded.","solutions":["Run a clean rebuild (mvn clean package or gradle clean build) to regenerate Panache augmentation metadata","Verify the class named in the message exists on the runtime classpath (check jar contents / dependency tree)","If the class was renamed or deleted, delete stale build output and reload the app","Check that no Gradle/Maven exclusion or classifier accidentally drops the entities jar"],"exampleFix":"// before: stale jar without com.acme.OldRepository\njava -jar app.jar\n// after: rebuild so metadata matches classes\nmvn clean package && java -jar target/app.jar","handlingStrategy":"validation","validationCode":"try {\n    Class.forName(repoClassName, false, Thread.currentThread().getContextClassLoader());\n    Class.forName(entityClassName, false, Thread.currentThread().getContextClassLoader());\n} catch (ClassNotFoundException e) {\n    throw new IllegalStateException(\"Class missing from classpath: \" + e.getMessage(), e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    repo.findAll().list();\n} catch (RuntimeException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Unable to load repository/entity class mapping\")) {\n        // rebuild / fix classpath\n    } else throw e;\n}","preventionTips":["Run a clean build after renaming or moving entities/repositories","Verify jar packaging includes all entity and repository classes","Avoid excluding ORM-related modules from the build","Keep repository classes in Jandex-indexed modules"],"tags":["quarkus","panache","classloading","classpath"],"backgroundTag":"classnotfound-classpath","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"}