flowable/flowable-engine · critical · FlowableException

Flowable database problem: ${errorMessage}

Error message

Flowable database problem: ${errorMessage}

What it means

After a successful version check, schemaCheckVersion verifies that the engine's tables are present; if not, it throws 'Flowable database problem: <missing component>'. The connected database lacks the required Flowable tables.

Source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/db/EngineSqlScriptBasedDbSchemaManager.java:61

    protected abstract String getDbVersionForChangelogVersion(String changeLogVersion);

    @Override
    public void schemaCheckVersion() {
        try {
            String dbVersion = getDbVersion();
            String currentVersion = getEngineVersion();
            if (!currentVersion.equals(dbVersion)) {
                throw new FlowableWrongDbException(currentVersion, dbVersion);
            }

            String errorMessage = null;
            if (!isEngineTablePresent()) {
                errorMessage = addMissingComponent(errorMessage, context);
            }

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

        } catch (Exception e) {
            if (isMissingTablesException(e)) {
                throw new FlowableException(
                        "No flowable tables in DB. Set property \"databaseSchemaUpdate\" \"true\" or value=\"create-drop\" (use create-drop for testing only!) for automatic schema creation",
                        e);
            } else {
                if (e instanceof RuntimeException) {
                    throw (RuntimeException) e;
                } else {
                    throw new FlowableException("couldn't get " + context + " db schema version", e);
                }
            }
        }

        logger.debug("flowable {} db schema check successful", context);
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Set databaseSchemaUpdate=true (or "create-drop" in tests) to create missing tables automatically.
  2. Run the DDL create scripts (org/flowable/db/create/*) manually for your database.
  3. Verify the JDBC URL points to the intended database/schema where tables exist.
  4. Check the DB user has SELECT on the metadata/tables and the tables aren't in another schema.

Example fix

// before
<property name="databaseSchemaUpdate" value="false" /> // empty DB
// after
<property name="databaseSchemaUpdate" value="true" />
Defensive patterns

Strategy: validation

Validate before calling

try (Connection c = dataSource.getConnection(); ResultSet rs = c.getMetaData().getTables(null, null, "ACT_GE_PROPERTY", new String[]{"TABLE"})) {
  if (!rs.next()) throw new IllegalStateException("Flowable tables missing; run schema creation first");
}

Try / catch

try { engineConfiguration.buildProcessEngine(); }
catch (FlowableException e) {
  if (e.getMessage().startsWith("Flowable database problem") || e.getMessage().contains("No flowable tables in DB")) { /* create schema or fix JDBC URL */ }
  throw e;
}

Prevention

When it happens

Trigger: Starting an engine against an empty or wrong database with databaseSchemaUpdate=false; tables were dropped; wrong schema/catalog selected so the table-existence check fails.

Common situations: Fresh environment where schema creation was never run; user connected to a different database/schema than intended; partial schema creation left the DB without engine tables.

Related errors

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