What causes "Flowable IDM database problem: ${errorMessage}" in flowable/flowable-engine?

Set databaseSchemaUpdate=true (or create-drop for testing) in processEngineConfiguration in flowable.cfg.xml so tables are created automatically.

flowable/flowable-engine · critical · FlowableException

Flowable IDM database problem: ${errorMessage}

Error message

Flowable IDM database problem: ${errorMessage}

What it means

Thrown by the IDM engine's schema version check when the required Flowable IDM database tables are absent or the schema is incompatible. It aggregates which components are missing (e.g. 'engine') into the message. Flowable validates the DB schema at engine bootstrap so it fails fast instead of failing later at runtime.

Source

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

   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) {
                   throw (RuntimeException) e;
               } else {
                   throw new FlowableException("couldn't get db schema version", e);
               }
           }
       }

       logger.debug("flowable idm db schema check successful");
   }

View on GitHub (pinned to d6d39ce1c6)

Solutions

Set databaseSchemaUpdate=true (or create-drop for testing) in processEngineConfiguration in flowable.cfg.xml so tables are created automatically.
Manually run the Flowable SQL scripts (org/flowable/idm/db/create/*.sql) for your database against the target schema.
Verify the datasource points at the database where the ACT_ID_* tables actually exist and that the user has SELECT rights.
Check schema version compatibility between the Flowable version and the DB (ACT_ID_PROPERTY schema.version).

Example fix

// before (flowable.cfg.xml)
<property name="databaseSchemaUpdate" value="false" />
// after
<property name="databaseSchemaUpdate" value="true" />

Defensive patterns

Strategy: validation

Validate before calling

try (Connection c = dataSource.getConnection()) {
  DatabaseMetaData md = c.getMetaData();
  try (ResultSet rs = md.getTables(null, null, "ACT_ID_PROPERTY", null)) {
    if (!rs.next()) throw new IllegalStateException("Flowable IDM tables missing — run schema create or set databaseSchemaUpdate=true");
  }
}

Try / catch

try {
  idmEngine = config.buildEngine();
} catch (FlowableException e) {
  if (e.getMessage().contains("database problem")) {
    // run schema creation scripts or enable databaseSchemaUpdate, then retry
  }
  throw e;
}

Prevention

Set databaseSchemaUpdate=true in non-production environments.
Keep DB migrations in the deploy pipeline when schema update is disabled in production.
Add a startup health check that verifies ACT_ID_* tables exist.
Use the same datasource for engine and manual SQL scripts.

When it happens

Trigger: Calling ProcessEngine/IdmEngine bootstrap with databaseSchemaUpdate=false (default) against a database that has no IDM tables (no ACT_ID_PROPERTY table), or a schema from an incompatible Flowable version.

Common situations: Fresh deployment pointing at an empty database; switching databases without re-running schema creation; a JDBC user without rights to read the tables; upgrading Flowable against an old schema.

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

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