YunaiV/ruoyi-vue-pro · critical · FlowableException

Error while building ibatis SqlSessionFactory: {}

Error message

Error while building ibatis SqlSessionFactory: {}

What it means

Flowable builds the MyBatis (formerly iBatis) SqlSessionFactory by reading the mapper XML and loading a per-dialect properties file (org/flowable/common/db/properties/<databaseType>.properties). Any failure during reading, property loading, or Configuration building is wrapped as FlowableException with the cause message. Common sub-causes: missing properties file for the databaseType, malformed mapper XML, classpath resource not found.

Source

Thrown at sql/dm/flowable-patch/src/main/java/org/flowable/common/engine/impl/AbstractEngineConfiguration.java:867

                // 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 0418084e22)

Solutions

1. Inspect the caused-by exception/message — 'pathToEngineDbProperties' / IOException points to a missing properties file, SAXException to bad mapper XML.
2. Ensure databaseType matches an existing org/flowable/common/db/properties/<type>.properties on the classpath.
3. Verify the flowable SQL mapper resources are included (check the shaded jar contents).
4. Pin a compatible MyBatis version if the cause is a NoSuchMethodError on Configuration.

Example fix

// before: wrong databaseType -> no properties file
cfg.setDatabaseType("dameng");
// after: use the key that has a properties resource
cfg.setDatabaseType("dm");

String propsPath = "org/flowable/common/db/properties/" + cfg.getDatabaseType() + ".properties";
if (getClass().getClassLoader().getResource(propsPath) == null)
    throw new IllegalStateException("Missing Flowable DB properties: " + propsPath);

null

try { engine = cfg.buildProcessEngine(); }
catch (FlowableException e) { log.error("MyBatis build failed: {}", e.getMessage(), e); throw e; }

When it happens

Trigger: setDatabaseType() set to a value with no matching properties file (e.g. 'dameng' when only 'dm' exists); a custom mapper XML with a syntax error; resource not on classpath in a shaded/fat jar; MyBatis version incompatibility.

Common situations: Adding a new DB dialect without shipping the .properties file; building a fat jar that loses flowable mapper resources; upgrading MyBatis to a version with a breaking Configuration API change.

Related errors

• couldn't lookup datasource from {}: {}
• DataSource or JDBC properties have to be specified in a proc
• couldn't deduct database type from database product name '{}
• invalid command interceptor chain configuration: {}
• Exception while initializing Database connection

AI-assisted analysis of YunaiV/ruoyi-vue-pro@0418084e22 (2026-08-14). Data as JSON: /api/errors/94909a1bbe3d8b4a. Report an issue: GitHub.