flowable/flowable-engine · error · ActivitiIllegalArgumentException

entityManagerFactory is null

Error message

entityManagerFactory is null

What it means

EntityManagerSessionFactory's constructor validates that the entityManagerFactory argument is non-null and throws ActivitiIllegalArgumentException immediately otherwise. JPA variable support requires a real jakarta.persistence.EntityManagerFactory to create EntityManagerSessions, so a null factory is rejected at session-factory construction time.

Solutions

1. Configure the EntityManagerFactory before creating the session factory (set jpaEntityManagerFactory in ProcessEngineConfiguration)
2. Ensure the Spring bean is defined and injected (LocalContainerEntityManagerFactoryBean)
3. Check that the property/bean reference name is spelled correctly and not resolving to null
4. Initialize JPA (persistence.xml, datasource) before engine startup

Example fix

// before
processEngineConfiguration.setJpaEntityManagerFactory(null);
// after
processEngineConfiguration.setJpaEntityManagerFactory(entityManagerFactory); // injected Spring bean

// validate before constructing the session factory
if (entityManagerFactory == null) {
  throw new IllegalStateException("configure jpaEntityManagerFactory before engine startup");
}

boolean validJpaFactory(Object emf) {
  return emf instanceof jakarta.persistence.EntityManagerFactory;
}

try {
  processEngineConfiguration.setJpaEntityManagerFactory(emf);
} catch (ActivitiIllegalArgumentException e) {
  logger.error("EntityManagerFactory missing/invalid: " + e.getMessage());
  throw e;
}

When it happens

Trigger: new EntityManagerSessionFactory(null, handleTransactions, closeEntityManager) — typically the JPA config property (jpaEntityManagerFactory / entityManagerFactory bean) was never set or resolved to null.

Common situations: Spring context missing the EntityManagerFactory bean (JPA not configured); wiring the process engine configuration without jpaHandleTransaction/jpa close settings but a null factory; bean name typo in XML/Java config.

Related errors

• entityManagerFactory is null
• Cannot set JPA variable:
• Cannot set JPA variable: " + EntityManagerSession.class + "…
• Cannot set JPA variable: not configured
• null value cannot be saved

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

Appendix: source

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

import jakarta.persistence.EntityManagerFactory;

import org.activiti.engine.ActivitiIllegalArgumentException;
import org.activiti.engine.impl.interceptor.Session;
import org.activiti.engine.impl.interceptor.SessionFactory;
import org.flowable.variable.service.impl.types.EntityManagerSession;

/**
 * @author Frederik Heremans
 */
public class EntityManagerSessionFactory implements SessionFactory {

    protected EntityManagerFactory entityManagerFactory;
    protected boolean handleTransactions;
    protected boolean closeEntityManager;

    public EntityManagerSessionFactory(Object entityManagerFactory, boolean handleTransactions, boolean closeEntityManager) {
        if (entityManagerFactory == null) {
            throw new ActivitiIllegalArgumentException("entityManagerFactory is null");
        }
        if (!(entityManagerFactory instanceof EntityManagerFactory)) {
            throw new ActivitiIllegalArgumentException("EntityManagerFactory must implement 'jakarta.persistence.EntityManagerFactory'");
        }

        this.entityManagerFactory = (EntityManagerFactory) entityManagerFactory;
        this.handleTransactions = handleTransactions;
        this.closeEntityManager = closeEntityManager;
    }

    @Override
    public Class<?> getSessionType() {
        return EntityManagerSession.class;
    }

    @Override
    public Session openSession() {
        return new EntityManagerSessionImpl(entityManagerFactory, handleTransactions, closeEntityManager);

View on GitHub (pinned to d6d39ce1c6)