quarkusio/quarkus · error · IllegalArgumentException

Missing attribute '${nodeName}.class'

Error message

Missing attribute '${nodeName}.class'

What it means

When parsing managed types (entity/mapped-superclass/embeddable) from a mapping file (orm.xml), Quarkus's JpaJandexScavenger calls safeGetClassName to extract the class attribute of the XML element. If the element has no 'class' attribute, the type cannot be identified and IllegalArgumentException('Missing attribute <nodeName>.class') is thrown.

Source

Thrown at extensions/hibernate-orm/deployment/src/main/java/io/quarkus/hibernate/orm/deployment/JpaJandexScavenger.java:263

        }

        enlistOrmXmlMappingListeners(collector, packagePrefix, managed.getEntityListenerContainer());
    }

    private void enlistOrmXmlMappingListeners(Collector collector, String packagePrefix,
            JaxbEntityListenerContainerImpl entityListeners) {
        if (entityListeners == null) {
            return;
        }
        for (var listener : entityListeners.getEntityListeners()) {
            collector.potentialCdiBeanTypes.add(DotName.createSimple(qualifyIfNecessary(packagePrefix, listener.getClazz())));
        }
    }

    private static String safeGetClassName(String packagePrefix, JaxbManagedType managedType, String nodeName) {
        String name = managedType.getClazz();
        if (name == null) {
            throw new IllegalArgumentException("Missing attribute '" + nodeName + ".class'");
        }
        return qualifyIfNecessary(packagePrefix, name);
    }

    // See org.hibernate.cfg.annotations.reflection.internal.XMLContext.buildSafeClassName(java.lang.String, java.lang.String)
    private static String qualifyIfNecessary(String packagePrefix, String name) {
        if (name.indexOf('.') < 0) {
            return packagePrefix + name;
        } else {
            // The class name is already qualified; don't apply the package prefix.
            return name;
        }
    }

    private void enlistHbmXmlMapping(Collector collector, JaxbHbmHibernateMapping mapping) {
        String packageValue = mapping.getPackage();
        String packagePrefix = packageValue == null ? "" : packageValue + ".";

View on GitHub (pinned to e1c734241f)

Solutions

1. Add the class attribute to the offending element in the orm.xml, e.g. <entity class="com.acme.MyEntity">
2. Locate the element by nodeName in the error message (it names the XML element) and fix it
3. Regenerate or validate the orm.xml against the JPA XSD, which can catch missing required attributes early

Example fix

<!-- before -->
<entity access="FIELD">
  <table name="T1"/>
</entity>
<!-- after -->
<entity class="com.acme.Thing" access="FIELD">
  <table name="T1"/>
</entity>

// Validate orm.xml elements carry class attributes before build
DocumentBuilderFactory f = DocumentBuilderFactory.newInstance();
NodeList entities = f.newDocumentBuilder().parse(new File("src/main/resources/META-INF/orm.xml"))
    .getElementsByTagName("entity");
for (int i = 0; i < entities.getLength(); i++) {
    if (((Element) entities.item(i)).getAttribute("class").isEmpty())
        throw new IllegalArgumentException("<entity> missing class attribute in orm.xml");
}

When it happens

Trigger: An orm.xml contains an <entity>, <mapped-superclass>, or <embeddable> element (the nodeName) without a class="..." attribute, and the element is processed via name()/safeGetClassName.

Common situations: Hand-written or generated orm.xml missing class attribute; XML copied from a catalog example with placeholders; XML manipulation/tooling that dropped attributes; mistakenly using <entity> for a package-level metadata element.

Related errors

• Cannot find ORM mapping file '${mappingFileName}' in the cla
• Annotation ${dotName} was not expected on a target of kind $
• Type ${className} must be annotated with @Embeddable, becaus
• Multiple ${AdditionalPersistenceUnitBuildItem} for persisten
• Hibernate %s persistence unit '%s' cannot be created for the

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