flowable/flowable-engine · error · FlowableException

no insert statement for ${entity.getClass()} in the ibatis m

Error message

no insert statement for ${entity.getClass()} in the ibatis mapping files

What it means

DbSqlSession.flushRegularInsert resolves the MyBatis insert statement id for an entity from DbSqlSessionFactory. If the mapping files define no insert statement for the entity's class, it throws FlowableException. This indicates an internal inconsistency: an entity was scheduled for insertion but has no corresponding SQL mapping.

Source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/db/DbSqlSession.java:536

    protected void flushInsertEntities(Class<? extends Entity> entityClass, Collection<Entity> entitiesToInsert) {
        if (entitiesToInsert.size() == 1) {
            flushRegularInsert(entitiesToInsert.iterator().next(), entityClass);
        } else if (Boolean.FALSE.equals(dbSqlSessionFactory.isBulkInsertable(entityClass))) {
            for (Entity entity : entitiesToInsert) {
                flushRegularInsert(entity, entityClass);
            }
        } else {
            flushBulkInsert(entitiesToInsert, entityClass);
        }
    }

    protected void flushRegularInsert(Entity entity, Class<? extends Entity> clazz) {
        String insertStatement = dbSqlSessionFactory.getInsertStatement(entity);
        insertStatement = dbSqlSessionFactory.mapStatement(insertStatement);

        if (insertStatement == null) {
            throw new FlowableException("no insert statement for " + entity.getClass() + " in the ibatis mapping files");
        }

        LOGGER.debug("inserting: {}", entity);
        sqlSession.insert(insertStatement, entity);

        // See https://activiti.atlassian.net/browse/ACT-1290
        if (entity instanceof HasRevision) {
            incrementRevision(entity);
        }
    }

    protected void flushBulkInsert(Collection<Entity> entities, Class<? extends Entity> clazz) {
        String insertStatement = dbSqlSessionFactory.getBulkInsertStatement(clazz);
        insertStatement = dbSqlSessionFactory.mapStatement(insertStatement);

        if (insertStatement == null) {
            throw new FlowableException("no insert statement for " + entities.iterator().next().getClass() + " in the ibatis mapping files");
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Register an insert statement for the entity class in the MyBatis mapping XML (id 'insert<SimpleClassName>') and include the mapping in dbSqlSessionFactory mappings.
2. Ensure all Flowable jars are the same version so no mapping files are missing.
3. If using a custom entity, extend the engine's entity insert logic and provide the mapping instead of relying on the default resolver.
4. Check the exception's entity class name and verify getInsertStatement/mapping conventions match it exactly.

Example fix

// before: custom entity without mapping
public class MyTaskEntityImpl implements Entity { ... } // no insert mapping -> error on flush
// after: add mapping resource
<insert id="insertMyTaskEntity" parameterType="com.myapp.MyTaskEntityImpl">
  insert into MY_TASK (ID_, NAME_) values (#{id}, #{name})
</insert>
// and register: factory.setMyBatisXmlMapping("com/myapp/MyTask.mapping.xml");

// custom entity check before inserting via DbSqlSession
String insertStatement = dbSqlSessionFactory.getInsertStatement(entity);
if (insertStatement == null) throw new IllegalStateException("No MyBatis insert mapping registered for " + entity.getClass());

try { taskService.saveTask(task); } catch (FlowableException e) { if (e.getMessage().contains("no insert statement for")) { log.error("Missing MyBatis mapping for entity class — register mapping XML"); } throw e; }

When it happens

Trigger: Flushing the persistence cache (flushInsertEntities/flushPersistentObjects) with a custom Entity subclass (or a new entity type) that has no 'insert<ClassName>' statement registered in the ibatis/MyBatis mapping configuration.

Common situations: Custom entity/EntityManager extensions plugged into the engine without adding corresponding MyBatis mapping XML; engine jar version mismatch where a mapping file is missing; misuse of the internal CommandContext/Entity API in custom commands.

Understand the failure class

Background: "This is a bug, please report it": internal invariant violations, unreachable panics, and SNH errors explained — this error's family across 47 libraries.

Related errors

• no delete statement for <persistentObjectClass> in the ibati
• no bulk delete statement for <persistentObjectClass> in the
• no insert statement for <persistentObjectClass> in the ibati
• no update statement for <updatedObjectClass> in the ibatis m
• Plan item could not be found for <elementId>

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