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.

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 + "…
• Cannot access id method/field for JPA Entity
• Deserialized value is not an array of ID's
• Entity does not exist

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

Appendix: 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)