quarkusio/quarkus · error · RuntimeException

Failed to read Model class

Error message

Failed to read Model class

What it means

In the same model-class enhancement flow, after the class bytes are read, an IOException while reading class bytes (or the enhance step reading the stream) is wrapped in a RuntimeException 'Failed to read Model class' with the original IOException as cause.

Source

Thrown at extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/HibernateOrmProcessor.java:1288

        for (io.quarkus.hibernate.orm.deployment.AdditionalJpaModelBuildItem additionalJpaModel : deprecatedAdditionalJpaModelBuildItems) {
            additionalClassNames.add(additionalJpaModel.getClassName());
        }
        for (String className : additionalClassNames) {
            try {
                byte[] bytes = IoUtil.readClassAsBytes(HibernateOrmProcessor.class.getClassLoader(), className);
                if (bytes == null) {
                    bytes = IoUtil.readClassAsBytes(Thread.currentThread().getContextClassLoader(), className);
                }
                if (bytes == null) {
                    throw new RuntimeException("Failed to read class bytes for '" + className
                            + "', class not present in class loaders: "
                            + HibernateOrmProcessor.class.getClassLoader()
                            + ", " + Thread.currentThread().getContextClassLoader());
                }
                byte[] enhanced = hibernateEntityEnhancer.enhance(className, bytes);
                additionalClasses.produce(new GeneratedClassBuildItem(false, className, enhanced != null ? enhanced : bytes));
            } catch (IOException e) {
                throw new RuntimeException("Failed to read Model class", e);
            }
        }
    }

    @BuildStep
    public JpaModelPerPersistenceUnitBuildItem buildJpaModelPerPersistenceUnit(HibernateOrmConfig hibernateOrmConfig,
            List<AdditionalJpaModelBuildItem> additionalJpaModelBuildItems, JpaModelBuildItem jpaModel,
            CombinedIndexBuildItem indexBuildItem) {
        IndexView index = indexBuildItem.getIndex();
        Map<String, JpaPersistenceUnitModel> modelPerPersistenceUnit = new HashMap<>();

        boolean hasPackagesInQuarkusConfig = hasPackagesInQuarkusConfig(hibernateOrmConfig);
        Collection<AnnotationInstance> packageLevelPersistenceUnitAnnotations = getPackageLevelPersistenceUnitAnnotations(
                index);

        Map<String, Set<String>> packageRules = new HashMap<>();

        Set<String> persistenceUnitsConfiguredThroughQuarkusConfiguration = new LinkedHashSet<>();

View on GitHub (pinned to e1c734241f)

Solutions

1. Inspect the IOException cause to find the offending resource, then delete/clean the corrupt artifact from the local Maven repo and rebuild
2. Run mvn clean install on the module containing the entity class
3. Check file permissions and disk state for the jars on the classpath

Example fix

// shell
rm -rf ~/.m2/repository/com/acme/entities
./mvnw clean install -f extensions/

// Verify jars on the classpath are readable/corruption-free:
new java.util.jar.JarFile(pathToEntitiesJar).close(); // throws if corrupt

try {
    // build / enhancement step
} catch (RuntimeException e) {
    if ("Failed to read Model class".equals(e.getMessage()) && e.getCause() instanceof java.io.IOException io) {
        // inspect io, clean corrupt artifact from ~/.m2 and rebuild
    }
    throw e;
}

When it happens

Trigger: IoUtil.readClassAsBytes throws IOException while reading bytes for a model class name from either classloader inside the enhancement loop.

Common situations: Corrupt jar/class file in the local Maven repository; truncated class resources from a partially-built dependency; jar file access issues (permissions, locked file on Windows).

Related errors

• An error occurred while processing ${resourceName}
• The Hibernate ORM configuration in Quarkus does not support
• Failed to read class bytes for '${className}', class not pre
• Unable to properly register the hierarchy of the following J
• Cannot find ORM mapping file '${mappingFileName}' in the cla

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