flowable/flowable-engine · critical · FlowableException

Flowable database problem: ${errorMessage}

Error message

Flowable database problem: ${errorMessage}

What it means

Thrown during schemaCheckVersion when one or more expected Flowable table groups (engine, history, and optionally others) are missing from the database; the missing components are accumulated in errorMessage and reported together. It signals an incomplete or partially-created Flowable schema.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/db/ProcessDbSchemaManager.java:53

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

            String errorMessage = null;
            if (!isEngineTablePresent()) {
                errorMessage = addMissingComponent(errorMessage, "engine");
            }
            if (CommandContextUtil.getDbSqlSession().getDbSqlSessionFactory().isDbHistoryUsed() && !isHistoryTablePresent()) {
                errorMessage = addMissingComponent(errorMessage, "history");
            }

            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 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 db schema check successful");
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Set databaseSchemaUpdate=true (or 'create-drop' in test) so the engine creates the missing tables, then restart.
2. Apply the complete DDL for your database from the engine's create scripts for the exact engine version.
3. If history tables were intentionally removed, configure dbHistoryUsed=false / historyLevel=none so the check does not require them.

Example fix

// before
<property name="databaseSchemaUpdate" value="false"/> <!-- history tables absent -->
// after
<property name="databaseSchemaUpdate" value="true"/> <!-- creates missing tables -->
<!-- or: <property name="dbHistoryUsed" value="false"/> -->

boolean engineTables = managementService.getProperties().containsKey("schema.version"); boolean historyTables = /* check ACT_HI_PROCINST exists via jdbc metadata */; if (!engineTables || !historyTables) { cfg.setDatabaseSchemaUpdate("true"); }

try { engine = cfg.buildProcessEngine(); } catch (FlowableException e) { if (e.getMessage().startsWith("Flowable database problem:")) { /* create missing tables */ } }

When it happens

Trigger: Database exists with some Flowable tables but is missing ACT_RE_* / ACT_RU_* / ACT_HI_* groups, e.g. a partial manual schema install, a failed create, or isDbHistoryUsed=true while history tables were never created.

Common situations: Manually running only a subset of DDL scripts; restoring a partial backup; dropping history tables to reclaim space while dbHistoryUsed remains true; schema creation interrupted mid-run.

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

• Flowable database problem: ${errorMessage}
• no flowable tables in db. set <property name="databaseSchema
• Activiti database problem: <errorMessage>
• no activiti tables in db. set <property name="databaseSchema
• Could not update Flowable database schema: unknown version f

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