flowable/flowable-engine · critical · FlowableException

Could not update Flowable database schema: unknown version f

Error message

Could not update Flowable database schema: unknown version from database: '

What it means

Thrown by FlowableVersions.getFlowableVersionIndexForDbVersion when the schema version recorded in the ACT_GE_PROPERTY table does not match any known Flowable release version (including the last v5/v6 versions), so the schema updater cannot determine how to migrate the database. This protects the engine from silently upgrading an unknown or foreign schema.

Source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/FlowableVersions.java:205

    public static int getFlowableVersionIndexForDbVersion(String dbVersion) {
        int matchingVersionIndex;
        
        if ("fox".equalsIgnoreCase(dbVersion)) {
            dbVersion = "5.13";
        }
        
        // Determine index in the sequence of Flowable releases
        matchingVersionIndex = findMatchingVersionIndex(dbVersion);

        // If no match has been found, but the version starts with '5.x',
        // we assume it's the last version (see comment in the VERSIONS list)
        if (matchingVersionIndex < 0 && dbVersion != null && dbVersion.startsWith("5.")) {
            matchingVersionIndex = findMatchingVersionIndex(FlowableVersions.LAST_V5_VERSION);
        }

        // Exception when no match was found: unknown/unsupported version
        if (matchingVersionIndex < 0) {
            throw new FlowableException("Could not update Flowable database schema: unknown version from database: '" + dbVersion + "'");
        }
        
        return matchingVersionIndex;
    }

    public static boolean hasCamMigrationVersion(String version) {
        int index = findMatchingCamMigrationIndex(version);
        if (index >= 0) {
            return true;
        } else {
            return false;
        }
    }
    
    protected static int findMatchingCamMigrationIndex(String dbVersion) {
        int index = 0;
        int matchingVersionIndex = -1;
        while (matchingVersionIndex < 0 && index < FlowableVersions.CAM_MIGRATION_VERSIONS.size()) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

Check the recorded version (ACT_GE_PROPERTY, property 'schema.version' or 'cfg.database-version') and compare with the Flowable version on the classpath; align the engine version with the DB (usually upgrade the library).
Never downgrade Flowable below the version that last wrote the schema; either restore the newer jar or restore a DB backup from before the upgrade.
Ensure all Flowable modules (engine, cmmn, idm, dmn, event-registry) are on the same version via a single flowable-root BOM dependency.
As a last resort for dev/test only, correct the version property manually after backing up the database.

Defensive patterns

Strategy: validation

Validate before calling

String dbVersion = managementService.getProperty("schema.version");
if (dbVersion != null && !SUPPORTED_VERSIONS.contains(dbVersion)) {
  throw new IllegalStateException("DB schema version " + dbVersion + " not supported by engine " + FlowableVersions.CURRENT_VERSION);
}

Try / catch

try {
  processEngine = ProcessEngineConfiguration.createProcessEngineConfigurationFromResource("flowable.cfg.xml").buildProcessEngine();
} catch (FlowableException e) {
  if (e.getMessage().contains("unknown version from database")) {
    // halt deployment: alert ops, do not auto-fix schema
  }
  throw e;
}

Prevention

Pin all Flowable modules to one version with the flowable-root BOM.
Never point a new engine version at a DB written by a newer one; check schema.version before startup.
Snapshot/backup the database before every engine upgrade.
Test schema upgrades against a staging copy first.

When it happens

Trigger: Engine startup with a database whose flowable version property contains an unrecognized string (e.g. '7.1.0.x-SNAPSHOT' from a dev build, a version from a newer Flowable release than the engine on the classpath, or a corrupted/empty property).

Common situations: Downgrading the Flowable jar against a database already upgraded by a newer engine; mixing modules of different Flowable versions; databases created by Activiti forks with odd version strings; manual edits or corruption of the schema version property.

Understand the failure class

Background: "is not a compatible type" / "cannot merge" errors: when a value's type doesn't match what the library requires — this error's family across 65 libraries.

Related errors

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