flowable/flowable-engine · critical · ActivitiException

Error while building ibatis SqlSessionFactory

Error message

Error while building ibatis SqlSessionFactory: ${e.getMessage()}

What it means

The engine builds its MyBatis SqlSessionFactory from bundled mapping XML files during initialization. Any exception in that process (unreadable mapping resource, XML/schema error, property substitution failure, driver registration issue) is wrapped in this ActivitiException with the underlying message preserved as cause.

Solutions

1. Inspect the nested cause (e.getCause()) for the real MyBatis parse/configuration error
2. Align the mybatis dependency version with the one required by your Activiti version (avoid bundling a conflicting copy)
3. Rebuild/redeploy the engine jar if mapping resources are missing (verify org/activiti/db/mapping XMLs on classpath)
4. Check for classloader/packaging issues if running inside an application server or shaded uber-jar

Example fix

// before (pom)
<dependency><groupId>org.mybatis</groupId><artifactId>mybatis</artifactId><version>3.5.0</version></dependency>
// after (match engine's tested version)
<dependency><groupId>org.mybatis</groupId><artifactId>mybatis</artifactId><version>3.2.x</version></dependency>

// before engine init, ensure mapping resources are reachable
classPathMustContain("org/activiti/db/mapping/mappings.xml");
try (InputStream in = ReflectUtil.getResourceAsStream("org/activiti/db/mapping/mappings.xml")) {
  if (in == null) throw new IllegalStateException("Activiti MyBatis mapping resources missing from classpath");
}

try {
  processEngine = cfg.buildProcessEngine();
} catch (ActivitiException e) {
  if (e.getMessage().startsWith("Error while building ibatis SqlSessionFactory")) {
    log.error("MyBatis init failed: {}", e.getCause(), e);
    throw new EngineInitializationException(e.getCause());
  } else throw e;
}

When it happens

Trigger: initSqlSessionFactory fails: the ibatis mapping XML stream cannot be read or parsed (corrupted jar, wrong classloader), MyBatis configuration errors in initMybatisConfiguration, or incompatible MyBatis version on the classpath.

Common situations: Shading/packaging the engine and losing META-INF resources; conflicting MyBatis versions on the classpath (app brings a different mybatis jar); custom XML mappings with invalid statements; classloader restrictions in exotic containers.

Related errors

• Error while building ibatis SqlSessionFactory:
• Activity needed for multi instance cannot bv found
• activity tenant id is null
• Booleans and null cannot be used in 'greater than' condition
• Booleans and null cannot be used in 'greater than or equal'…

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cfg/ProcessEngineConfigurationImpl.java:885

                if ((databaseWildcardEscapeCharacter != null) && (databaseWildcardEscapeCharacter.length() != 0)) {
                    wildcardEscapeClause = " escape '" + databaseWildcardEscapeCharacter + "'";
                }
                properties.put("wildcardEscapeClause", wildcardEscapeClause);

                if (databaseType != null) {
                    properties.put("limitBefore", DbSqlSessionFactory.databaseSpecificLimitBeforeStatements.get(databaseType));
                    properties.put("limitAfter", DbSqlSessionFactory.databaseSpecificLimitAfterStatements.get(databaseType));
                    properties.put("limitBetween", DbSqlSessionFactory.databaseSpecificLimitBetweenStatements.get(databaseType));
                    properties.put("limitOuterJoinBetween", DbSqlSessionFactory.databaseOuterJoinLimitBetweenStatements.get(databaseType));
                    properties.put("orderBy", DbSqlSessionFactory.databaseSpecificOrderByStatements.get(databaseType));
                    properties.put("limitBeforeNativeQuery", Objects.toString(DbSqlSessionFactory.databaseSpecificLimitBeforeNativeQueryStatements.get(databaseType), ""));
                }

                Configuration configuration = initMybatisConfiguration(environment, reader, properties);
                sqlSessionFactory = new DefaultSqlSessionFactory(configuration);

            } catch (Exception e) {
                throw new ActivitiException("Error while building ibatis SqlSessionFactory: " + e.getMessage(), e);
            } finally {
                IoUtil.closeSilently(inputStream);
            }
        }
    }

    protected Configuration initMybatisConfiguration(Environment environment, Reader reader, Properties properties) {
        XMLConfigBuilder parser = new XMLConfigBuilder(reader, "", properties);
        Configuration configuration = parser.getConfiguration();
        configuration.setEnvironment(environment);

        initMybatisTypeHandlers(configuration);
        initCustomMybatisMappers(configuration);

        configuration = parseMybatisConfiguration(configuration, parser);
        return configuration;
    }

View on GitHub (pinned to d6d39ce1c6)