flowable/flowable-engine · error · ActivitiIllegalArgumentException

Class is not a JPA-entity:

Error message

Class is not a JPA-entity:

What it means

getJPAEntity loads an entity from its stored class name and id. Before doing so it resolves EntityMetaData for the class; a null result means the class is not recognized as a JPA entity, so the stored variable cannot be materialized.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/variable/JPAEntityMappings.java:118

            throw new ActivitiException("Illegal argument exception when getting value from id method/field on JPAEntity", iae);
        } catch (IllegalAccessException iae) {
            throw new ActivitiException("Cannot access id method/field for JPA Entity", iae);
        } catch (InvocationTargetException ite) {
            throw new ActivitiException("Exception occurred while getting value from id field/method on JPAEntity: " +
                    ite.getCause().getMessage(), ite.getCause());
        }

        // Fall trough when no method and field is set
        throw new ActivitiException("Cannot get id from JPA Entity, no id method/field set");
    }

    public Object getJPAEntity(String className, String idString) {
        Class<?> entityClass = null;
        entityClass = ReflectUtil.loadClass(className);

        EntityMetaData metaData = getEntityMetaData(entityClass);
        if (metaData == null) {
            throw new ActivitiIllegalArgumentException("Class is not a JPA-entity: " + className);
        }

        // Create primary key of right type
        Object primaryKey = createId(metaData, idString);
        return findEntity(entityClass, primaryKey);
    }

    private Object findEntity(Class<?> entityClass, Object primaryKey) {
        EntityManager em = Context
                .getCommandContext()
                .getSession(EntityManagerSession.class)
                .getEntityManager();

        Object entity = em.find(entityClass, primaryKey);
        if (entity == null) {
            throw new ActivitiException("Entity does not exist: " + entityClass.getName() + " - " + primaryKey);
        }
        return entity;

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Restore the class to its original package/name or keep a compatibility class so old variables still resolve
  2. Re-annotate the class with @Entity and rebuild metadata
  3. Migrate old variable rows (ACT_RU_VARIABLE / ACT_HI_VARINST) to the new class name
  4. Remove or recreate the affected process variables

Example fix

// before
package com.old; @Entity public class Order {...}
// after (moved)
package com.new; @Entity public class Order {...}
// plus migration of stored class name com.old.Order -> com.new.Order
Defensive patterns

Strategy: validation

Validate before calling

try {
    Class<?> c = ReflectUtil.loadClass(className);
    if (!c.isAnnotationPresent(Entity.class)) {
        throw new IllegalArgumentException(className + " is not an entity");
    }
} catch (ActivitiException e) { /* stale class name in variables */ }

Type guard

boolean isResolvableEntity(String className) {
    try {
        return Class.forName(className).isAnnotationPresent(javax.persistence.Entity.class);
    } catch (ClassNotFoundException e) { return false; }
}

Try / catch

try {
    Object entity = mappings.getJPAEntity(className, idString);
} catch (ActivitiIllegalArgumentException e) {
    if (e.getMessage().startsWith("Class is not a JPA-entity")) {
        // migrate or delete stale variables referencing renamed classes
    } else { throw e; }
}

Prevention

When it happens

Trigger: Deserializing a JPA entity variable whose stored class name no longer resolves to entity metadata — class renamed/moved, @Entity removed, or the variable was created with a non-entity class.

Common situations: Application upgrade renaming/moving entity packages so old process variables reference stale class names; entity removed from the persistence unit; typo in configured class name in a JPA variable lookup.

Related errors

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/00e12854cb7a9957. Report an issue: GitHub.