flowable/flowable-engine · error · ActivitiException

Cannot set JPA variable: not configured

Error message

Cannot set JPA variable:  not configured

What it means

Thrown by JPAEntityVariableType.setValue when no EntityManagerSession is available in the current command context. JPA entity variables require a configured JPA persistence context so the engine can flush pending changes and read the entity's primary key.

Source

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

    public boolean isCachable() {
        return forceCacheable;
    }

    @Override
    public boolean isAbleToStore(Object value) {
        if (value == null) {
            return true;
        }
        return mappings.isJPAEntity(value);
    }

    @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 != null) {
            String className = mappings.getJPAClassString(value);
            String idString = mappings.getJPAIdString(value);
            valueFields.setTextValue(className);
            valueFields.setTextValue2(idString);
        } else {
            valueFields.setTextValue(null);
            valueFields.setTextValue2(null);
        }
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Configure jpaEntityManagerFactory (or jpaPersistenceUnitName) on the process engine configuration.
2. In Spring, add the <property name="jpaEntityManagerFactory" .../> / EntityManagerFactory bean wiring before setting JPA variables.
3. If the value is not actually a managed entity, use a plain serializable type variable instead.
4. Catch ActivitiException and fail with an actionable configuration message.

Example fix

// before
SpringProcessEngineConfiguration cfg = new SpringProcessEngineConfiguration();
cfg.setDataSource(dataSource); // no JPA configured
// after
cfg.setJpaEntityManagerFactory(entityManagerFactory);
cfg.setJpaHandleTransaction(true);
cfg.setJpaCloseEntityManager(true);

if (processEngineConfiguration.getJpaEntityManagerFactory() == null && processEngineConfiguration.getJpaPersistenceUnitName() == null) throw new IllegalStateException("JPA not configured; cannot use JPA entity variables");

try { runtimeService.setVariable(id, "entity", entity); } catch (ActivitiException e) { log.error("JPA EntityManagerSession missing - configure jpaEntityManagerFactory", e); }

When it happens

Trigger: Setting a JPA-entity-valued process variable via runtimeService/taskService when the process engine configuration has no jpaPersistenceUnitName/jpaEntityManagerFactory configured.

Common situations: Forgetting to set jpaEntityManagerFactory or jpaPersistenceUnitName on SpringProcessEngineConfiguration; running engine commands outside a context that bootstrapped the EntityManager session; unit tests without JPA configuration.

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:
• Cannot set JPA variable: " + EntityManagerSession.class + "
• The maximum allowed length must be greater than 0
• The variable value does not contain an operator value
• The variable value does not have a type

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