flowable/flowable-engine · error · FlowableException

Error while building ibatis SqlSessionFactory:

Error message

Error while building ibatis SqlSessionFactory: 

What it means

The engine builds its MyBatis SqlSessionFactory from the bundled MyBatis XML mapping configuration. If any exception occurs while reading or initializing that configuration, it is rethrown as this FlowableException with the original cause attached.

Source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/AbstractEngineConfiguration.java:842

                // set default properties
                properties.put("limitBefore", "");
                properties.put("limitAfter", "");
                properties.put("limitBetween", "");
                properties.put("limitBeforeNativeQuery", "");
                properties.put("limitAfterNativeQuery", "");
                properties.put("blobType", "BLOB");
                properties.put("boolValue", "TRUE");

                if (databaseType != null) {
                    properties.load(getResourceAsStream(pathToEngineDbProperties()));
                }

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

            } catch (Exception e) {
                throw new FlowableException("Error while building ibatis SqlSessionFactory: " + e.getMessage(), e);
            } finally {
                IoUtil.closeSilently(inputStream);
            }
        } else {
            // This is needed when the SQL Session Factory is created by another engine.
            // When custom XML Mappers are registered with this engine they need to be loaded in the configuration as well
            applyCustomMybatisCustomizations(sqlSessionFactory.getConfiguration());
        }
    }

    public String pathToEngineDbProperties() {
        return "org/flowable/common/db/properties/" + databaseType + ".properties";
    }

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

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Inspect the wrapped cause (e.getCause()) for the real MyBatis failure
2. Verify the MyBatis XML mapping files exist on the classpath and are valid
3. Check for MyBatis version conflicts in the dependency tree (mvn dependency:tree)
4. Fix any custom type alias/type handler registrations referenced in the config

try { engine = cfg.buildProcessEngine(); } catch (FlowableException e) { if (e.getMessage().startsWith("Error while building ibatis SqlSessionFactory")) { log.error("MyBatis init failed", e.getCause()); } throw e; }

When it happens

Trigger: AbstractEngineConfiguration.initSqlSessionFactory() when parsing/loading the MyBatis XML config or initMybatisConfiguration fails: corrupt/unreadable XML resource, bad custom type alias/type handler registration, missing mybatis dependency, incompatible mapping XML.

Common situations: Custom MyBatis XML mappers registered incorrectly, classpath packaging issues (config XML missing from jar), conflicting MyBatis versions on the classpath, invalid custom type alias/type handler entries.

Related errors

• Form engine is not initialized
• Failed to load type alias class
• Failed to load type handler class
• Could not read IDM Mybatis configuration file
• Could not parse Mybatis configuration file

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