{"record":{"id":"ed39b231872ce3d1","repo":"flowable/flowable-engine","slug":"error-while-building-ibatis-sqlsessionfactory-e","errorCode":null,"errorMessage":"Error while building ibatis SqlSessionFactory: ${e.getMessage()}","messagePattern":"Error while building ibatis SqlSessionFactory: (.+?)","errorType":"exception","errorClass":"ActivitiException","httpStatus":null,"severity":"critical","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cfg/ProcessEngineConfigurationImpl.java","lineNumber":885,"sourceCode":"                if ((databaseWildcardEscapeCharacter != null) && (databaseWildcardEscapeCharacter.length() != 0)) {\n                    wildcardEscapeClause = \" escape '\" + databaseWildcardEscapeCharacter + \"'\";\n                }\n                properties.put(\"wildcardEscapeClause\", wildcardEscapeClause);\n\n                if (databaseType != null) {\n                    properties.put(\"limitBefore\", DbSqlSessionFactory.databaseSpecificLimitBeforeStatements.get(databaseType));\n                    properties.put(\"limitAfter\", DbSqlSessionFactory.databaseSpecificLimitAfterStatements.get(databaseType));\n                    properties.put(\"limitBetween\", DbSqlSessionFactory.databaseSpecificLimitBetweenStatements.get(databaseType));\n                    properties.put(\"limitOuterJoinBetween\", DbSqlSessionFactory.databaseOuterJoinLimitBetweenStatements.get(databaseType));\n                    properties.put(\"orderBy\", DbSqlSessionFactory.databaseSpecificOrderByStatements.get(databaseType));\n                    properties.put(\"limitBeforeNativeQuery\", Objects.toString(DbSqlSessionFactory.databaseSpecificLimitBeforeNativeQueryStatements.get(databaseType), \"\"));\n                }\n\n                Configuration configuration = initMybatisConfiguration(environment, reader, properties);\n                sqlSessionFactory = new DefaultSqlSessionFactory(configuration);\n\n            } catch (Exception e) {\n                throw new ActivitiException(\"Error while building ibatis SqlSessionFactory: \" + e.getMessage(), e);\n            } finally {\n                IoUtil.closeSilently(inputStream);\n            }\n        }\n    }\n\n    protected Configuration initMybatisConfiguration(Environment environment, Reader reader, Properties properties) {\n        XMLConfigBuilder parser = new XMLConfigBuilder(reader, \"\", properties);\n        Configuration configuration = parser.getConfiguration();\n        configuration.setEnvironment(environment);\n\n        initMybatisTypeHandlers(configuration);\n        initCustomMybatisMappers(configuration);\n\n        configuration = parseMybatisConfiguration(configuration, parser);\n        return configuration;\n    }\n","sourceCodeStart":867,"sourceCodeEnd":903,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/cfg/ProcessEngineConfigurationImpl.java#L867-L903","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the nested cause (e.getCause()) for the real MyBatis parse/configuration error","Align the mybatis dependency version with the one required by your Activiti version (avoid bundling a conflicting copy)","Rebuild/redeploy the engine jar if mapping resources are missing (verify org/activiti/db/mapping XMLs on classpath)","Check for classloader/packaging issues if running inside an application server or shaded uber-jar"],"exampleFix":"// before (pom)\n<dependency><groupId>org.mybatis</groupId><artifactId>mybatis</artifactId><version>3.5.0</version></dependency>\n// after (match engine's tested version)\n<dependency><groupId>org.mybatis</groupId><artifactId>mybatis</artifactId><version>3.2.x</version></dependency>","handlingStrategy":"try-catch","validationCode":"// before engine init, ensure mapping resources are reachable\nclassPathMustContain(\"org/activiti/db/mapping/mappings.xml\");\ntry (InputStream in = ReflectUtil.getResourceAsStream(\"org/activiti/db/mapping/mappings.xml\")) {\n  if (in == null) throw new IllegalStateException(\"Activiti MyBatis mapping resources missing from classpath\");\n}","typeGuard":null,"tryCatchPattern":"try {\n  processEngine = cfg.buildProcessEngine();\n} catch (ActivitiException e) {\n  if (e.getMessage().startsWith(\"Error while building ibatis SqlSessionFactory\")) {\n    log.error(\"MyBatis init failed: {}\", e.getCause(), e);\n    throw new EngineInitializationException(e.getCause());\n  } else throw e;\n}","preventionTips":["Pin the MyBatis version required by your Activiti release","Avoid uber-jar shading that drops XML mapping resources","Verify classpath resources org/activiti/db/mapping/*.xml exist in the deployed artifact","Read e.getCause() first — it carries the real MyBatis error"],"tags":["activiti","mybatis","initialization"],"backgroundTag":"module-init-failed","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}