flowable/flowable-engine · error · FlowableException

Error while flushing EntityManager, illegal state

Error message

Error while flushing EntityManager, illegal state

What it means

EntityManagerSessionImpl.flush() calls entityManager.flush() and wraps failures. When the JPA provider throws IllegalStateException (EntityManager in wrong state, e.g. already closed or not joined to a transaction), Flowable rethrows it as FlowableException 'Error while flushing EntityManager, illegal state' with the original as cause.

Source

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

    public EntityManagerSessionImpl(EntityManagerFactory entityManagerFactory, EntityManager entityManager, boolean handleTransactions, boolean closeEntityManager) {
        this(entityManagerFactory, handleTransactions, closeEntityManager);
        this.entityManager = entityManager;
    }

    public EntityManagerSessionImpl(EntityManagerFactory entityManagerFactory, boolean handleTransactions, boolean closeEntityManager) {
        this.entityManagerFactory = entityManagerFactory;
        this.handleTransactions = handleTransactions;
        this.closeEntityManager = closeEntityManager;
    }

    @Override
    public void flush() {
        if (entityManager != null && (!handleTransactions || isTransactionActive())) {
            try {
                entityManager.flush();
            } catch (IllegalStateException ise) {
                throw new FlowableException("Error while flushing EntityManager, illegal state", ise);
            } catch (TransactionRequiredException tre) {
                throw new FlowableException("Cannot flush EntityManager, an active transaction is required", tre);
            } catch (PersistenceException pe) {
                throw new FlowableException("Error while flushing EntityManager: " + pe.getMessage(), pe);
            }
        }
    }

    protected boolean isTransactionActive() {
        if (handleTransactions && entityManager.getTransaction() != null) {
            return entityManager.getTransaction().isActive();
        }
        return false;
    }

    @Override
    public void close() {
        if (closeEntityManager && entityManager != null && entityManager.isOpen()) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Do not close or clear the EntityManager yourself when it is managed by the Flowable/JPA session; let the session close it
2. Ensure flush is called while the EM is joined to an active transaction (check isTransactionActive before manual flush)
3. Align jpaHandleTransactions/jpaCloseEntityManager settings with your transaction manager configuration
4. Inspect the cause (ise) to identify which EM lifecycle rule was violated and fix the calling code

Example fix

// before
entityManager.close(); // closed too early
// flowable session flush -> IllegalStateException
// after
// let the session manage lifecycle; no manual close
engineConfig.setJpaCloseEntityManager(true);

if (entityManager != null && !entityManager.isOpen()) {
    throw new IllegalStateException("EntityManager already closed; do not close it manually before the command completes");
}

try {
    session.flush();
} catch (org.flowable.common.engine.api.FlowableException e) {
    if (e.getMessage().contains("illegal state") && e.getCause() instanceof IllegalStateException) {
        log.error("EntityManager in invalid state at flush; check lifecycle/close handling", e.getCause());
    }
    throw e;
}

When it happens

Trigger: Session flush at command end while the EntityManager is closed or in an invalid lifecycle state; flushing an application-managed EntityManager that was closed manually; using the EM outside its intended transaction scope while handleTransactions semantics expect a valid state.

Common situations: Closing the EntityManager in application code before the Flowable command completes; mixing application-managed and container-managed persistence contexts; transaction infrastructure misconfiguration causing the EM to be detached/closed at flush time.

Understand the failure class

Background: "Invalid state transition" errors: "status must be X, actually Y", "already rejected/charging/uninstalled", "cannot ... while running" — what they mean when a library rejects your call — this error's family across 31 libraries.

Related errors

• Cannot flush EntityManager, an active transaction is require
• entityManagerFactory is null
• EntityManagerFactory must implement 'jakarta.persistence.Ent
• Error while flushing EntityManager:
• Cannot flush EntityManager, an active transaction is require

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