flowable/flowable-engine · error · ActivitiWrongDbException

version mismatch: activiti library version is '<libraryVersi

Error message

version mismatch: activiti library version is '<libraryVersion>', db version is <dbVersion> Hint: 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

What it means

dbSchemaCheckVersion() reads the engine's schema version from the ACT_GE_PROPERTY table and compares it to ProcessEngine.VERSION. A mismatch throws ActivitiWrongDbException with this message, naming the library version and the DB schema version. The hint tells you to set databaseSchemaUpdate=true (or create-drop for tests) so the engine upgrades/creates the schema automatically.

Source

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

    public void close() {
        sqlSession.close();
    }

    public void commit() {
        sqlSession.commit();
    }

    public void rollback() {
        sqlSession.rollback();
    }

    // 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",

View on GitHub (pinned to d6d39ce1c6)

Solutions

  1. Set <property name="databaseSchemaUpdate" value="true"/> in flowable.cfg.xml so the engine upgrades the schema at startup (use create-drop only for testing).
  2. Back up the database and run the official upgrade scripts (DB-specific SQL in the engine distribution's upgrade folder) matching your version delta, then restart.
  3. Verify you are connecting to the intended database (check JDBC URL) and that only one engine version uses this schema.

Example fix

// before: flowable.cfg.xml
<bean id="processEngineConfiguration" class="...ProcessEngineConfigurationImpl">
  <property name="databaseSchemaUpdate" value="false"/>

// after
<property name="databaseSchemaUpdate" value="true"/>
Defensive patterns

Strategy: validation

Validate before calling

// Check schema version before building the engine
String dbVersion = jdbcTemplate.queryForObject(
    "SELECT VALUE_ FROM ACT_GE_PROPERTY WHERE NAME_ = 'schema.version'", String.class);
if (!ProcessEngine.VERSION.equals(dbVersion)) {
    throw new IllegalStateException("Schema " + dbVersion + " != engine " + ProcessEngine.VERSION
        + " — run upgrade scripts or set databaseSchemaUpdate=true");
}

Try / catch

try {
    ProcessEngines.buildProcessEngine();
} catch (ActivitiWrongDbException e) {
    log.error("Schema {} does not match engine {}", e.getDbVersion(), e.getLibraryVersion());
    throw e;
}

Prevention

When it happens

Trigger: Starting/creating a ProcessEngine against a database whose ACT_GE_PROPERTY.schema.version differs from the engine jar version, e.g. deploying a newer flowable-engine against an old schema or pointing at a DB created by another product version.

Common situations: Engine upgrade without schema migration; multiple engine versions sharing one database; restoring an old DB dump under a new engine; accidentally pointing dev config at a production DB with a different schema version.

Related errors

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