{"record":{"id":"7f066b3ec9208e16","repo":"flowable/flowable-engine","slug":"version-mismatch-activiti-library-version-is-li","errorCode":null,"errorMessage":"version mismatch: activiti library version is '<libraryVersion>', db version is <dbVersion> Hint: Set <property name=\"databaseSchemaUpdate\" to value=\"true\" or value=\"create-drop\" (use create-drop for testing only!) in bean processEngineConfiguration in flowable.cfg.xml for automatic schema creation","messagePattern":"version mismatch: activiti library version is '<libraryVersion>', db version is <dbVersion> Hint: Set <property name=\"databaseSchemaUpdate\" to value=\"true\" or value=\"create-drop\" \\(use create-drop for testing only!\\) in bean processEngineConfiguration in flowable\\.cfg\\.xml for automatic schema creation","errorType":"exception","errorClass":"ActivitiWrongDbException","httpStatus":null,"severity":"error","filePath":"modules/flowable5-engine/src/main/java/org/activiti/engine/impl/db/DbSqlSession.java","lineNumber":929,"sourceCode":"    public void close() {\n        sqlSession.close();\n    }\n\n    public void commit() {\n        sqlSession.commit();\n    }\n\n    public void rollback() {\n        sqlSession.rollback();\n    }\n\n    // schema operations ////////////////////////////////////////////////////////\n\n    public void dbSchemaCheckVersion() {\n        try {\n            String dbVersion = getDbVersion();\n            if (!ProcessEngine.VERSION.equals(dbVersion)) {\n                throw new ActivitiWrongDbException(ProcessEngine.VERSION, dbVersion);\n            }\n\n            String errorMessage = null;\n            if (!isEngineTablePresent()) {\n                errorMessage = addMissingComponent(errorMessage, \"engine\");\n            }\n            if (dbSqlSessionFactory.isDbHistoryUsed() && !isHistoryTablePresent()) {\n                errorMessage = addMissingComponent(errorMessage, \"history\");\n            }\n\n            if (errorMessage != null) {\n                throw new ActivitiException(\"Activiti database problem: \" + errorMessage);\n            }\n\n        } catch (Exception e) {\n            if (isMissingTablesException(e)) {\n                throw new ActivitiException(\n                        \"no activiti tables in db. set <property name=\\\"databaseSchemaUpdate\\\" to value=\\\"true\\\" or value=\\\"create-drop\\\" (use create-drop for testing only!) in bean processEngineConfiguration in flowable.cfg.xml for automatic schema creation\",","sourceCodeStart":911,"sourceCodeEnd":947,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable5-engine/src/main/java/org/activiti/engine/impl/db/DbSqlSession.java#L911-L947","documentation":"dbSchemaCheckVersion() reads the engine's schema version from the ACT_GE_PROPERTY table and compares it to ProcessEngine.VERSION. A mismatch throws ActivitiWrongDbException with this message, naming the library version and the DB schema version. The hint tells you to set databaseSchemaUpdate=true (or create-drop for tests) so the engine upgrades/creates the schema automatically.","triggerScenarios":"Starting/creating a ProcessEngine against a database whose ACT_GE_PROPERTY.schema.version differs from the engine jar version, e.g. deploying a newer flowable-engine against an old schema or pointing at a DB created by another product version.","commonSituations":"Engine upgrade without schema migration; multiple engine versions sharing one database; restoring an old DB dump under a new engine; accidentally pointing dev config at a production DB with a different schema version.","solutions":["Set <property name=\"databaseSchemaUpdate\" value=\"true\"/> in flowable.cfg.xml so the engine upgrades the schema at startup (use create-drop only for testing).","Back up the database and run the official upgrade scripts (DB-specific SQL in the engine distribution's upgrade folder) matching your version delta, then restart.","Verify you are connecting to the intended database (check JDBC URL) and that only one engine version uses this schema."],"exampleFix":"// before: flowable.cfg.xml\n<bean id=\"processEngineConfiguration\" class=\"...ProcessEngineConfigurationImpl\">\n  <property name=\"databaseSchemaUpdate\" value=\"false\"/>\n\n// after\n<property name=\"databaseSchemaUpdate\" value=\"true\"/>","handlingStrategy":"validation","validationCode":"// Check schema version before building the engine\nString dbVersion = jdbcTemplate.queryForObject(\n    \"SELECT VALUE_ FROM ACT_GE_PROPERTY WHERE NAME_ = 'schema.version'\", String.class);\nif (!ProcessEngine.VERSION.equals(dbVersion)) {\n    throw new IllegalStateException(\"Schema \" + dbVersion + \" != engine \" + ProcessEngine.VERSION\n        + \" — run upgrade scripts or set databaseSchemaUpdate=true\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    ProcessEngines.buildProcessEngine();\n} catch (ActivitiWrongDbException e) {\n    log.error(\"Schema {} does not match engine {}\", e.getDbVersion(), e.getLibraryVersion());\n    throw e;\n}","preventionTips":["Keep one engine version per database schema; never share a schema across engine versions.","Run the official upgrade scripts whenever bumping the engine dependency.","Pin the engine version in deployments and align DB migrations with release notes."],"tags":["database","schema","version-mismatch","startup"],"backgroundTag":"schema-version-mismatch","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}