{"record":{"id":"b997ec45268a24d0","repo":"YunaiV/yudao-cloud","slug":"error-while-building-ibatis-sqlsessionfactory","errorCode":null,"errorMessage":"Error while building ibatis SqlSessionFactory: {}","messagePattern":"Error while building ibatis SqlSessionFactory: (.+?)","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"critical","filePath":"sql/dm/flowable-patch/src/main/java/org/flowable/common/engine/impl/AbstractEngineConfiguration.java","lineNumber":867,"sourceCode":"\n                // set default properties\n                properties.put(\"limitBefore\", \"\");\n                properties.put(\"limitAfter\", \"\");\n                properties.put(\"limitBetween\", \"\");\n                properties.put(\"limitBeforeNativeQuery\", \"\");\n                properties.put(\"limitAfterNativeQuery\", \"\");\n                properties.put(\"blobType\", \"BLOB\");\n                properties.put(\"boolValue\", \"TRUE\");\n\n                if (databaseType != null) {\n                    properties.load(getResourceAsStream(pathToEngineDbProperties()));\n                }\n\n                Configuration configuration = initMybatisConfiguration(environment, reader, properties);\n                sqlSessionFactory = new DefaultSqlSessionFactory(configuration);\n\n            } catch (Exception e) {\n                throw new FlowableException(\"Error while building ibatis SqlSessionFactory: \" + e.getMessage(), e);\n            } finally {\n                IoUtil.closeSilently(inputStream);\n            }\n        } else {\n            // This is needed when the SQL Session Factory is created by another engine.\n            // When custom XML Mappers are registered with this engine they need to be loaded in the configuration as well\n            applyCustomMybatisCustomizations(sqlSessionFactory.getConfiguration());\n        }\n    }\n\n    public String pathToEngineDbProperties() {\n        return \"org/flowable/common/db/properties/\" + databaseType + \".properties\";\n    }\n\n    public Configuration initMybatisConfiguration(Environment environment, Reader reader, Properties properties) {\n        XMLConfigBuilder parser = new XMLConfigBuilder(reader, \"\", properties);\n        Configuration configuration = parser.getConfiguration();\n","sourceCodeStart":849,"sourceCodeEnd":885,"githubUrl":"https://github.com/YunaiV/yudao-cloud/blob/477be9dd49ab7223a972a6abdff0684d6423dec3/sql/dm/flowable-patch/src/main/java/org/flowable/common/engine/impl/AbstractEngineConfiguration.java#L849-L885","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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').","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).","Align all flowable-* artifacts to the same version (mvn dependency:tree | grep flowable).","Validate custom mapper XMLs with an XML parser; remove them temporarily to isolate the failure."],"exampleFix":"# before\ncfg.setDatabaseType(\"dm\"); # no dm.properties resource -> NPE -> this error\n\n# after\ncfg.setDatabaseType(\"oracle\"); # DM is Oracle-compatible; oracle.properties ships with Flowable","handlingStrategy":"try-catch","validationCode":"// verify the properties resource resolves before engine build\nString path = \"org/flowable/common/db/properties/\" + databaseType + \".properties\";\nif (Thread.currentThread().getContextClassLoader().getResource(path) == null) {\n    throw new IllegalStateException(\"Missing Flowable db properties: \" + path\n        + \" — set databaseType to a shipped value (e.g. oracle)\");\n}","typeGuard":null,"tryCatchPattern":"try { engine = cfg.buildProcessEngine(); }\ncatch (FlowableException e) {\n    if (e.getMessage().startsWith(\"Error while building ibatis SqlSessionFactory\")) {\n        log.error(\"cause:\", e.getCause()); // NPE => missing properties file for databaseType\n    }\n    throw e;\n}","preventionTips":["Check dependency tree for mixed flowable-* versions before upgrading","For DM, pre-create the dm.properties resource or pin databaseType to 'oracle'","Lint custom MyBatis mapper XMLs in CI"],"tags":["flowable","mybatis","database","configuration","dameng"],"backgroundTag":null,"analyzedSha":"477be9dd49ab7223a972a6abdff0684d6423dec3","analyzedAt":"2026-08-14T13:35:31.121Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}