quarkusio/quarkus · error · RuntimeException

Failed to read class bytes for '${className}', class not pre

Error message

Failed to read class bytes for '${className}', class not present in class loaders: ${classLoader1}, ${classLoader2}

What it means

During bytecode processing of model classes (entity enhancement), the processor reads the class bytes from the processor's classloader, falling back to the context classloader. If neither can provide the bytes, it throws a RuntimeException naming the class and both classloaders.

Source

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

                    .setClassToTransform(i)
                    .setVisitorFunction(hibernateEntityEnhancer)
                    .setCacheable(true).build());
        }
        Set<String> additionalClassNames = new HashSet<>();
        for (AdditionalJpaModelBuildItem additionalJpaModel : additionalJpaModelBuildItems) {
            additionalClassNames.add(additionalJpaModel.getClassName());
        }
        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<>();

View on GitHub (pinned to e1c734241f)

Solutions

1. Ensure all entity/model classes are part of the application archive and its dependencies (not generated post-index or excluded)
2. Verify the dependency containing the class is a normal application dependency, not provided/optional with wrong scope
3. Clean and rebuild (mvn clean install) to remove stale build artifacts

Example fix

// pom.xml
// before
<dependency>
  <groupId>com.acme</groupId><artifactId>entities</artifactId><scope>provided</scope>
</dependency>
// after
<dependency>
  <groupId>com.acme</groupId><artifactId>entities</artifactId>
</dependency>

Class<?> c = Class.forName("com.acme.MyEntity", false,
    Thread.currentThread().getContextClassLoader());
if (c == null) { throw new IllegalStateException("Model class not on app classpath"); }

When it happens

Trigger: IoUtil.readClassAsBytes returns null for a class name in the JPA model from both HibernateOrmProcessor.class.getClassLoader() and the thread context classloader while enhancing/listing model classes.

Common situations: Entity classes generated at build time but not yet on the processor classloader; classes referenced by entities living in a jar excluded from the application archive; unusual classloading setups in custom packaging.

Related errors

• Failed to read Model class
• Bytecode enhancement failed for class '<entityName>' (it mig
• Unable to load class [<className>]
• Failed to load steps from %s
• The class (${name}) cannot be created during deployment.

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