YunaiV/yudao-cloud · critical · FlowableException

Error while building ibatis SqlSessionFactory: {}

Error message

Error while building ibatis SqlSessionFactory: {}

What it means

While building the MyBatis SqlSessionFactory, Flowable loads the MyBatis mapper XMLs and per-database properties (org/flowable/common/db/properties/<databaseType>.properties). Any exception during resource loading, parsing, or configuration is wrapped in this FlowableException with the cause's message.

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 477be9dd49)

Solutions

1. Read e.getCause() — an NPE on properties.load means the properties file for the current databaseType is missing; set databaseType to one that ships a file (e.g. 'oracle').
2. Add the missing properties file on the classpath at org/flowable/common/db/properties/<type>.properties (DM deployments commonly copy oracle.properties to dm.properties).
3. Align all flowable-* artifacts to the same version (mvn dependency:tree | grep flowable).
4. Validate custom mapper XMLs with an XML parser; remove them temporarily to isolate the failure.

Example fix

# before
cfg.setDatabaseType("dm"); # no dm.properties resource -> NPE -> this error

# after
cfg.setDatabaseType("oracle"); # DM is Oracle-compatible; oracle.properties ships with Flowable

// verify the properties resource resolves before engine build
String path = "org/flowable/common/db/properties/" + databaseType + ".properties";
if (Thread.currentThread().getContextClassLoader().getResource(path) == null) {
    throw new IllegalStateException("Missing Flowable db properties: " + path
        + " — set databaseType to a shipped value (e.g. oracle)");
}

try { engine = cfg.buildProcessEngine(); }
catch (FlowableException e) {
    if (e.getMessage().startsWith("Error while building ibatis SqlSessionFactory")) {
        log.error("cause:", e.getCause()); // NPE => missing properties file for databaseType
    }
    throw e;
}

When it happens

Trigger: databaseType resolves to a value with no matching properties file (e.g. 'dm' when only oracle/mysql/... files exist); a custom mybatisConfigurationFile with XML errors; a classpath conflict where two Flowable versions supply incompatible mapper XMLs; getResourceAsStream returns null -> NPE inside the try block.

Common situations: Running Flowable on DM after setting databaseType to an unmapped name; mixing Flowable JAR versions (flowable-engine 7.x with flowable-common 6.x); a malformed custom mapper XML registered via setCustomMybatisMappers; shaded/fat-jar builds that drop the properties resource.

Related errors

• couldn't deduct database type from database product name '{}
• Cannot determine the Oracle database version number
• couldn't lookup datasource from {}: {}
• DataSource or JDBC properties have to be specified in a proc
• Exception while initializing Database connection

AI-assisted analysis of YunaiV/yudao-cloud@477be9dd49 (2026-08-14). Data as JSON: /api/errors/b997ec45268a24d0. Report an issue: GitHub.