What causes "entityClass is null" in flowable/flowable-engine?

Ensure a concrete Flowable entity class (e.g. TaskEntity.class, ExecutionEntityImpl.class) is passed to getTableName; never pass a null Class

flowable/flowable-engine · error · FlowableIllegalArgumentException

entityClass is null

Error message

entityClass is null

What it means

GetTableNameCmd resolves the database table name for an entity class via EntityToTableMap. The command requires a non-null entity Class to look up the mapping, so it validates at the start of execute() and throws FlowableIllegalArgumentException if none was supplied.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/cmd/GetTableNameCmd.java:43

    private static final long serialVersionUID = 1L;

    protected Class<?> entityClass;
    protected boolean withPrefix = true;

    public GetTableNameCmd(Class<?> entityClass) {
        this.entityClass = entityClass;
    }

    public GetTableNameCmd(Class<?> entityClass, boolean withPrefix) {
        this.entityClass = entityClass;
        this.withPrefix = withPrefix;
    }

    @Override
    public String execute(CommandContext commandContext) {
        if (entityClass == null) {
            throw new FlowableIllegalArgumentException("entityClass is null");
        }

        String databaseTablePrefix = getDbSqlSession(commandContext).getDbSqlSessionFactory().getDatabaseTablePrefix();
        String tableName = EntityToTableMap.getTableName(entityClass);

        if (withPrefix) {
            return databaseTablePrefix + tableName;
        } else {
            return tableName;
        }
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

Ensure a concrete Flowable entity class (e.g. TaskEntity.class, ExecutionEntityImpl.class) is passed to getTableName; never pass a null Class
If the class is resolved dynamically, verify the Class lookup (Class.forName / loader) succeeded before calling the command
Check that the variable holding the entity type is initialized on all branches before invoking the command

Example fix

// before
String table = managementService.getTableName(entityClass, true); // entityClass is null
// after
if (entityClass == null) {
    throw new IllegalStateException("entity class must be resolved before getTableName");
}
String table = managementService.getTableName(entityClass, true);

Defensive patterns

Strategy: validation

Validate before calling

if (entityClass == null) {
    throw new IllegalArgumentException("entityClass must be provided");
}

Type guard

boolean hasEntityClass(Object c) {
    return c instanceof Class<?> && Entity.class.isAssignableFrom((Class<?>) c);
}

Try / catch

try {
    String table = managementService.getTableName(entityClass, true);
} catch (FlowableIllegalArgumentException e) {
    // entityClass was null; fix caller
    throw new IllegalStateException("entityClass required for table lookup", e);
}

Prevention

Always pass a concrete entity class literal, not a nullable variable
Validate dynamic class resolution before invoking the command

When it happens

Trigger: Calling managementService.getTableName(EntityClass, withPrefix) (or executing GetTableNameCmd directly) with a null Class argument, e.g. passing a variable that was expected to hold an entity class but is null.

Common situations: Reflectively resolving an entity class by name where the class name is wrong or the class failed to load; generic helper code that forwards an entity class parameter which is null on some code paths.

Related errors

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