quarkusio/quarkus · error · RuntimeException

Your repository class was not properly detected and assigne

Error message

Your repository class  was not properly detected and assigned an entity type

What it means

Panache repositories are mapped to their entity classes during build-time augmentation. getRepositoryEntityClass looks up this mapping at runtime; if a repository implementation class has no entry, the repository was not processed by the Panache enhancement step and cannot be used.

Source

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

        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;
    }

    //
    // Instance

    private Class<SessionType> sessionType;

    protected AbstractJpaOperations(Class<SessionType> sessionType) {
        this.sessionType = sessionType;
    }

    protected abstract PanacheQueryType createPanacheQuery(SessionType session, Class<?> entityClass, String query,
            String originalQuery,
            Sort sort,
            Object paramsArrayOrMap);

View on GitHub (pinned to e1c734241f)

Solutions

Make the repository extend PanacheRepository (or PanacheRepositoryBase) and be a @ApplicationScoped CDI bean
Ensure the class is in a module indexed by Jandex (add jandex Gradle/Maven plugin or META-INF/jandex.idx for third-party jars)
Rebuild/re-augment the application so Panache records the repository->entity mapping
Check that no @Exclude or build-step filter drops the repository class from processing

Example fix

// before
class PersonRepo { EntityManager em; ... }
// after
@ApplicationScoped
public class PersonRepo implements PanacheRepository<Person> { }

Defensive patterns

Strategy: validation

Validate before calling

if (!PanacheRepository.class.isAssignableFrom(repo.getClass())) {
    throw new IllegalStateException("Repository must extend PanacheRepository to be auto-mapped to an entity");
}

Type guard

boolean isValidPanacheRepository(Class<?> c) {
    return PanacheRepository.class.isAssignableFrom(c);
}

Try / catch

try {
    repository.findById(id);
} catch (RuntimeException e) {
    if (e.getMessage() != null && e.getMessage().contains("was not properly detected and assigned an entity type")) {
        // repository not enhanced: check Jandex indexing and PanacheRepository inheritance
    } else throw e;
}

Prevention

Always extend PanacheRepository/PanacheRepositoryBase
Make repositories CDI beans (@ApplicationScoped), don't instantiate them manually
Ensure all business modules have the Jandex plugin applied
Rebuild after adding new repository classes

When it happens

Trigger: Invoking a Panache repository method whose implementation class was not registered via setRepositoryClassesToEntityClasses — e.g. a repository instantiated manually, placed in a non-indexed module, or not extending PanacheRepository so the augmentor skipped it.

Common situations: Repository in a plain (non-Quarkus) jar without Jandex index; a repository class created at runtime via proxy/reflection; Quarkus app not re-augmented after adding the repository; using a custom base repository class that the augmentor does not recognize.

Related errors

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