flowable/flowable-engine · error · FlowableException

Cannot set JPA variable: ${session} not configured

Error message

Cannot set JPA variable: ${session} not configured

What it means

JPAEntityVariableType.setValue needs the EntityManagerSession from the current CommandContext to flush pending changes and resolve the entity's id. If no EntityManagerSession is registered (JPA not configured for this engine), it throws before touching the entity.

Source

Thrown at modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/types/JPAEntityVariableType.java:60

    @Override
    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 FlowableException("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 the engine with JPA: set jpaPersistenceUnitName (or jpaEntityManagerFactory) on SpringProcessEngineConfiguration / ProcessEngineConfiguration so an EntityManagerSession is registered.
2. Verify the variable is set on the same engine instance that has JPA configured, not a second default engine.
3. In tests, add the JPA configuration to the test engine builder or mock/stub the EntityManagerSession.
4. If JPA variables were never intended, pass the entity's id (String/Long) instead of the entity object itself.

Example fix

// before
ProcessEngineConfiguration.createStandaloneProcessEngineConfiguration()...buildProcessEngine();
// after
SpringProcessEngineConfiguration cfg = new SpringProcessEngineConfiguration();
cfg.setJpaPersistenceUnitName("myUnit"); // registers EntityManagerSession

EntityManagerSession s = Context.getCommandContext().getSession(EntityManagerSession.class); // inside command, or simply check engine config
if (processEngineConfiguration.getJpaEntityManagerFactory() == null && processEngineConfiguration.getJpaPersistenceUnitName() == null) throw new IllegalStateException("JPA not configured for this engine");

boolean jpaEnabled(ProcessEngineConfiguration cfg) { return cfg.getJpaEntityManagerFactory() != null || cfg.getJpaPersistenceUnitName() != null; }

try { runtimeService.setVariable(executionId, "entity", jpaEntity); } catch (FlowableException e) { if (e.getMessage().contains("EntityManagerSession") && e.getMessage().contains("not configured")) { throw new IllegalStateException("Enable JPA on the process engine configuration", e); } throw e; }

When it happens

Trigger: Calling setValue (e.g. runtimeService.setVariable / taskService.setVariable with a JPA entity value) while the process engine was built without jpaPersistenceUnitName/jpaEntityManagerFactory configuration.

Common situations: Forgetting jpa-persistence-unit / jpaEntityManagerFactory in the engine config after adding JPA variable usage; unit tests using the default in-memory engine config without JPA; multiple engines where the wrong (non-JPA) engine executes the variable write.

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

• Error while closing EntityManager, may have already been clo
• Error while flushing EntityManager, illegal state
• Error while closing EntityManager, may have already been clo
• Expecting a SpringProcessEngineConfiguration for the Camel m
• CmmnEngineConfiguration is required

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