flowable/flowable-engine · critical · FlowableWrongDbException

Wrong database version

Error message

Wrong database version

What it means

IdmDbSchemaManager.schemaCheckVersion() compares the IDM engine schema version recorded in the IDM property table against the running IdmEngine.VERSION. Flowable throws FlowableWrongDbException when they differ, refusing to run against a schema created by an incompatible engine version (and it also reports missing engine tables in the message).

Source

Thrown at modules/flowable-idm-engine/src/main/java/org/flowable/idm/engine/impl/db/IdmDbSchemaManager.java:75

   @Override
   protected boolean isUpdateNeeded() {
       boolean propertyTablePresent = isTablePresent(IDM_PROPERTY_TABLE);
       if (!propertyTablePresent) {
           return isIdmGroupTablePresent();
       }
       return true;
   }
   
   public boolean isIdmGroupTablePresent() {
       return isTablePresent("ACT_ID_GROUP");
   }
   
   @Override
   public void schemaCheckVersion() {
       try {
           String dbVersion = getSchemaVersion();
           if (!IdmEngine.VERSION.equals(dbVersion)) {
               throw new FlowableWrongDbException(IdmEngine.VERSION, dbVersion);
           }

           String errorMessage = null;
           if (!isTablePresent(IDM_PROPERTY_TABLE)) {
               errorMessage = addMissingComponent(errorMessage, "engine");
           }

           if (errorMessage != null) {
               throw new FlowableException("Flowable IDM database problem: " + errorMessage);
           }

       } catch (Exception e) {
           if (isMissingTablesException(e)) {
               throw new FlowableException(
                       "no flowable 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",
                       e);
           } else {
               if (e instanceof RuntimeException) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Upgrade the database schema using the SQL upgrade scripts for your target Flowable version (org/flowable/idm/db/upgrade/*)
2. Align all flowable-* engine dependencies to the same version in your build
3. Point the engine at the correct database/schema it was provisioned against
4. If the schema is unused/dev-only, set databaseSchemaUpdate=true to create/upgrade automatically
5. If the exception reports missing tables, run the full create scripts for the current version

Example fix

// before
<dependency>
  <artifactId>flowable-idm-engine</artifactId>
  <version>6.7.2</version>
</dependency> <!-- engine 6.7.2 vs schema from 6.4.2 -->
// after
<dependency>
  <artifactId>flowable-idm-engine</artifactId>
  <version>6.4.2</version>
</dependency> <!-- or run upgrade scripts 6.4.2 -> 6.7.2 -->

// check schema version before engine use
String dbVersion = /* read from IDM property table via admin SQL */;
if (!org.flowable.idm.engine.IdmEngine.VERSION.equals(dbVersion)) { runUpgradeScripts(dbVersion); }

boolean schemaVersionMatches(String dbVersion) { return org.flowable.idm.engine.IdmEngine.VERSION.equals(dbVersion); }

try { idmEngineConfiguration.buildEngine(); } catch (FlowableWrongDbException e) { log.error("DB schema version " + e.getDbVersion() + " != engine " + e.getLibraryVersion() + "; run upgrade scripts"); }

When it happens

Trigger: Starting/using the IDM engine after upgrading flowable-idm-engine jars without running the schema upgrade scripts; pointing the engine at a database created by an older/newer Flowable version; connecting to a database missing the IDM property table entirely.

Common situations: Dependency bumps (e.g. 6.x -> 7.x) without executing the DB upgrade SQL; shared database with another app running a different Flowable version; partial schema creation where tables exist but the version property row doesn't.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• version mismatch: library version is '${engineVersion}', db
• version mismatch: library version is '${FlowableVersions.CUR
• Wrong db version: expected ${ProcessEngine.VERSION}, found $
• version mismatch: library version is '${libraryVersion}', db
• There are app definitions with key = '' and version = ''

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/21628486a50fcf97. Report an issue: GitHub.