flowable/flowable-engine · error · FlowableIllegalArgumentException

entityManagerFactory is null

Error message

entityManagerFactory is null

What it means

The EntityManagerSessionFactory constructor validates its first argument: if the provided entityManagerFactory Object is null it throws FlowableIllegalArgumentException 'entityManagerFactory is null'. This factory wires JPA entity managers into Flowable's JPA variable type support.

Source

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

import jakarta.persistence.EntityManagerFactory;

import org.flowable.common.engine.api.FlowableIllegalArgumentException;
import org.flowable.common.engine.impl.interceptor.CommandContext;
import org.flowable.common.engine.impl.interceptor.Session;
import org.flowable.common.engine.impl.interceptor.SessionFactory;

/**
 * @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 FlowableIllegalArgumentException("entityManagerFactory is null");
        }
        if (!(entityManagerFactory instanceof EntityManagerFactory)) {
            throw new FlowableIllegalArgumentException("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(CommandContext commandContext) {
        return new EntityManagerSessionImpl(entityManagerFactory, handleTransactions, closeEntityManager);

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Configure processEngineConfiguration.setJpaEntityManagerFactory(entityManagerFactory) with a valid jakarta.persistence.EntityManagerFactory
2. In Spring, define/inject a LocalContainerEntityManagerFactoryBean and verify it is not null at wiring time
3. If you don't use JPA variables, disable the JPA configuration instead of passing null

Example fix

// before
engineConfig.setJpaEntityManagerFactory(null);
// after
EntityManagerFactory emf = Persistence.createEntityManagerFactory("myPU");
engineConfig.setJpaEntityManagerFactory(emf);

if (entityManagerFactory == null) {
    throw new IllegalArgumentException("jpaEntityManagerFactory must be configured before enabling JPA variable support");
}
if (!(entityManagerFactory instanceof jakarta.persistence.EntityManagerFactory)) {
    throw new IllegalArgumentException("object must implement jakarta.persistence.EntityManagerFactory");
}

boolean isValidEmf(Object o) {
    return o instanceof jakarta.persistence.EntityManagerFactory;
}

try {
    config.setJpaEntityManagerFactory(emf);
} catch (org.flowable.common.engine.api.FlowableIllegalArgumentException e) {
    log.error("JPA EntityManagerFactory missing/invalid: {}", e.getMessage());
    throw e;
}

When it happens

Trigger: Constructing EntityManagerSessionFactory(null, handleTransactions, closeEntityManager), typically from process engine configuration where the JPA EntityManagerFactory property was not set (jpaEntityManagerFactory null in config).

Common situations: Enabling JPA variable support (jpaHandleTransaction/jpaCloseEntityManager) but forgetting to set jpaEntityManagerFactory; Spring wiring where the LocalContainerEntityManagerFactoryBean bean is missing or not injected yet; copy-pasted config from non-JPA projects.

Related errors

• DMN repository service is not available
• No taskFormHandler specified for '
• Form engine is not initialized
• EntityManagerFactory must implement 'jakarta.persistence.Ent
• Error while flushing EntityManager, illegal state

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