flowable/flowable-engine · error · ActivitiException

Activiti database problem: <errorMessage>

Error message

Activiti database problem: <errorMessage>

What it means

dbSchemaCheckVersion() builds an errorMessage listing required schema components (engine, history, etc.) whose tables are missing via addMissingComponent(); if any are absent it throws this ActivitiException. It means the connected database exists but is missing required Activiti/Flowable tables for the components the configuration uses.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/db/DbSqlSession.java:941

    // schema operations ////////////////////////////////////////////////////////

    public void dbSchemaCheckVersion() {
        try {
            String dbVersion = getDbVersion();
            if (!ProcessEngine.VERSION.equals(dbVersion)) {
                throw new ActivitiWrongDbException(ProcessEngine.VERSION, dbVersion);
            }

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

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

        } catch (Exception e) {
            if (isMissingTablesException(e)) {
                throw new ActivitiException(
                        "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",
                        e);
            } else {
                if (e instanceof RuntimeException) {
                    throw (RuntimeException) e;
                } else {
                    throw new ActivitiException("couldn't get db schema version", e);
                }
            }
        }

        LOGGER.debug("activiti db schema check successful");
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Set <property name="databaseSchemaUpdate" value="true"/> in flowable.cfg.xml so missing tables are created at startup (create-drop for tests only).
2. Run the DB-specific create scripts from the engine distribution to create the missing ACT_* tables manually.
3. Check the JDBC URL/credentials point at the correct schema, and confirm the DB user can see the tables (grants).
4. If history is intentionally unused, disable it (dbHistoryUsed / historyLevel none) so the history table check is skipped.

Example fix

// before: empty DB, check-only
<property name="databaseSchemaUpdate" value="false"/>

// after: let engine create missing tables
<property name="databaseSchemaUpdate" value="true"/>

// Check required tables exist before engine startup
for (String t : new String[]{"ACT_GE_PROPERTY", "ACT_RU_EXECUTION", "ACT_HI_PROCINST"}) {
    Integer n = jdbcTemplate.queryForObject(
        "SELECT COUNT(*) FROM information_schema.tables WHERE table_name = ?", Integer.class, t);
    if (n == null || n == 0) throw new IllegalStateException("Missing table " + t + " — enable databaseSchemaUpdate");
}

try {
    ProcessEngines.buildProcessEngine();
} catch (ActivitiException e) {
    if (e.getMessage().startsWith("Activiti database problem")) {
        log.error("Missing Activiti tables: {}", e.getMessage());
    }
    throw e;
}

When it happens

Trigger: databaseSchemaUpdate=false (or 'false' variant that only checks) while connecting to an empty or partially initialized schema; dbSqlSessionFactory.isDbHistoryUsed() is true but history tables were dropped; a partial manual schema creation.

Common situations: Fresh database with schema creation disabled; someone dropped ACT_* tables (e.g. history cleanup gone wrong); wrong JDBC URL pointing at an empty schema; DB user lacking SELECT on the tables so presence checks fail.

Related errors

• Flowable database problem: ${errorMessage}
• Flowable database problem: ${errorMessage}
• no flowable tables in db. set <property name="databaseSchema
• version mismatch: activiti library version is '<libraryVersi
• no activiti tables in db. set <property name="databaseSchema

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