quarkusio/quarkus · error · RuntimeException

Unable to load repository/entity class mapping ->

Error message

Unable to load repository/entity class mapping  -> 

What it means

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.

Source

Thrown at extensions/panache/hibernate-orm-panache-common/runtime/src/main/java/io/quarkus/hibernate/orm/panache/common/runtime/AbstractJpaOperations.java:63

        if (entityToPersistenceUnitIsIncomplete == null) {
            entityToPersistenceUnitIsIncomplete = incomplete;
        } else {
            entityToPersistenceUnitIsIncomplete = entityToPersistenceUnitIsIncomplete || incomplete;
        }
    }

    private static volatile Map<Class<?>, Class<?>> repositoryClassToEntityClass = Collections.emptyMap();

    public static void setRepositoryClassesToEntityClasses(Map<String, String> map) {
        Map<Class<?>, Class<?>> converted = new HashMap<>();
        ClassLoader classLoader = Thread.currentThread().getContextClassLoader();
        for (Entry<String, String> entry : map.entrySet()) {
            try {
                Class<?> repoClass = Class.forName(entry.getKey(), false, classLoader);
                Class<?> entityClass = Class.forName(entry.getValue(), false, classLoader);
                converted.put(repoClass, entityClass);
            } catch (ClassNotFoundException e) {
                throw new RuntimeException("Unable to load repository/entity class mapping "
                        + entry.getKey() + " -> " + entry.getValue(), e);
            }
        }
        repositoryClassToEntityClass = Collections.unmodifiableMap(converted);
    }

    public static <Entity> Class<? extends Entity> getRepositoryEntityClass(
            // FIXME: if we move this to JpaOperations we can add a type constraint on the repo class
            Class<?> repositoryImplementationClass) {
        Class<?> ret = repositoryClassToEntityClass.get(repositoryImplementationClass);
        if (ret == null) {
            throw new RuntimeException("Your repository class " + repositoryImplementationClass
                    + " was not properly detected and assigned an entity type");
        }
        return (Class<? extends Entity>) ret;
    }

    //

View on GitHub (pinned to e1c734241f)

Solutions

1. Run a clean rebuild (mvn clean package or gradle clean build) to regenerate Panache augmentation metadata
2. Verify the class named in the message exists on the runtime classpath (check jar contents / dependency tree)
3. If the class was renamed or deleted, delete stale build output and reload the app
4. Check that no Gradle/Maven exclusion or classifier accidentally drops the entities jar

Example fix

// before: stale jar without com.acme.OldRepository
java -jar app.jar
// after: rebuild so metadata matches classes
mvn clean package && java -jar target/app.jar

try {
    Class.forName(repoClassName, false, Thread.currentThread().getContextClassLoader());
    Class.forName(entityClassName, false, Thread.currentThread().getContextClassLoader());
} catch (ClassNotFoundException e) {
    throw new IllegalStateException("Class missing from classpath: " + e.getMessage(), e);
}

try {
    repo.findAll().list();
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Unable to load repository/entity class mapping")) {
        // rebuild / fix classpath
    } else throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• The class (${name}) cannot be created during deployment.
• Unable to load class '{className}' for supporting custom JSO
• Failed to load CodeGenProvider class from deployment classlo
• Failed to read %s
• Failed to read resources from classpath

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