flowable/flowable-engine · error · ActivitiException

Cannot set JPA variable: " + EntityManagerSession.class + "

Error message

Cannot set JPA variable: " + EntityManagerSession.class + " not configured

What it means

Thrown by JPAEntityListVariableType.setValue() when no EntityManagerSession is registered in the CommandContext. Storing a JPA entity list as a process variable requires a configured JPA persistence provider; without it the engine cannot flush pending changes before persisting, so it aborts with ActivitiException.

Source

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

                for (Object entity : list) {
                    canStore = entity != null && mappings.isJPAEntity(entity) && mappings.getEntityMetaData(entity.getClass()).getEntityClass().equals(entityClass);
                    if (!canStore) {
                        // In case the object is not a JPA entity or the class doesn't match, we can't store the list
                        break;
                    }
                }
            }
        }
        return canStore;
    }

    @Override
    public void setValue(Object value, ValueFields valueFields) {
        EntityManagerSession entityManagerSession = Context
                .getCommandContext()
                .getSession(EntityManagerSession.class);
        if (entityManagerSession == null) {
            throw new ActivitiException("Cannot set JPA variable: " + EntityManagerSession.class + " not configured");
        } else {
            // Before we set the value we must flush all pending changes from the entitymanager
            // If we don't do this, in some cases the primary key will not yet be set in the object
            // which will cause exceptions down the road.
            entityManagerSession.flush();
        }

        if (value instanceof List<?> && ((List<?>) value).size() > 0) {
            List<?> list = (List<?>) value;
            List<String> ids = new ArrayList<>();

            String type = mappings.getJPAClassString(list.get(0));
            for (Object entry : list) {
                ids.add(mappings.getJPAIdString(entry));
            }

            // Store type in text field and the ID's as a serialized array
            valueFields.setBytes(serializeIds(ids));

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Configure the engine with EntityManagerSessionFactory (processEngineConfiguration.setJpaEntityManagerFactory(...) or jpaEntityManagerFactory property)
2. Ensure EntityManagerSession is available in the current CommandContext (JTA/Spring integration registering the session)
3. Do not pass JPA entities as variables if JPA support is not configured; store IDs instead and look up entities in code
4. Verify the variable type resolves to JPAEntityListVariableType only intentionally

Example fix

// before
ProcessEngineConfiguration.createStandaloneProcessEngineConfiguration(); // no JPA
// after
config.setJpaEntityManagerFactory(entityManagerFactory)
      .setJpaHandleTransaction(true)
      .setJpaCloseEntityManager(true);

// guard before setting an entity-list variable
if (processEngineConfig.getJpaEntityManagerFactory() == null) {
    throw new IllegalStateException("Configure jpaEntityManagerFactory before storing JPA entities as variables");
}

boolean jpaConfigured = Context.getCommandContext().getSession(EntityManagerSession.class) != null;

try {
    runtimeService.setVariable(executionId, "orders", orderList);
} catch (ActivitiException e) {
    if (e.getMessage().contains("not configured")) {
        // fall back to storing IDs instead of entities
    }
    throw e;
}

When it happens

Trigger: Setting a process variable that is a List of JPA entities (or JPAEntityListVariableType handles the value) while the process engine was not configured with jpaPersistenceEngine / EntityManagerSessionFactory; running with a basic engine configuration lacking the JPA session.

Common situations: Engine config missing jpaEntityManagerFactory / EntityManagerSessionFactory bean; calling runtimeService.setVariable(...) with an entity list on a non-JPA-configured engine; disabling JPA support but still passing entities as variables.

Understand the failure class

Background: "X is required", "must be set", "cannot be empty": the missing-required-config error family, from Vertex AI project/location to WeChat keys — this error's family across 18 libraries.

Related errors

• Cannot set JPA variable:
• JPA entity variables can only be used in 'variableValueEqual
• Variables containing a list of JPA entities cannot be used t
• Value is not a list of JPA entities: " + value
• Unexpected exception when serializing JPA id's

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