flowable/flowable-engine · error · FlowableException

Schema version property is not set

Error message

Schema version property is not set

What it means

getSchemaVersion() reads the schema version from the DB property table using a per-service schemaVersionProperty column name (e.g. 'schema.version'). If that property name was never configured on this ServiceSqlScriptBasedDbSchemaManager, it throws FlowableException because it cannot know where to read the version from. This is a misconfiguration of the schema manager itself, not a DB problem.

Source

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

        }
        return feedback;
    }
    
    @Override
    public void schemaCheckVersion() {
        String dbVersion = getSchemaVersion();
        if (!FlowableVersions.CURRENT_VERSION.equals(dbVersion)) {
            throw new FlowableWrongDbException(FlowableVersions.CURRENT_VERSION, dbVersion);
        }
    }

    protected boolean isUpdateNeeded() {
        return isTablePresent(table);
    }

    protected String getSchemaVersion() {
        if (schemaVersionProperty == null) {
            throw new FlowableException("Schema version property is not set");
        }
        String dbVersion = getProperty(schemaVersionProperty);
        if (dbVersion == null) {
            return getUpgradeStartVersion();
        }
        return dbVersion;
    }
    
    protected String getUpgradeStartVersion() {
        return "6.1.2.0"; // last version before most services were separated. Start upgrading from this point.
    }

}

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Set the schema version property on the manager configuration (e.g. setSchemaVersionProperty("schema.version") or the equivalent XML/config property)
2. Use Flowable's standard ProcessEngineConfiguration instead of manually constructing the schema manager so defaults are applied
3. Check that your custom subclass constructor invokes the parent setup that initializes schemaVersionProperty

Example fix

// before
ServiceSqlScriptBasedDbSchemaManager mgr = new ServiceSqlScriptBasedDbSchemaManager();
mgr.schemaCheckVersion();

// after
mgr.setSchemaVersionProperty("schema.version");
mgr.schemaCheckVersion();

// When constructing a custom schema manager, assert configuration first
if (mgr.getSchemaVersionProperty() == null) {
    throw new IllegalStateException("schemaVersionProperty must be set before schema operations");
}

try {
    mgr.schemaCheckVersion();
} catch (FlowableException e) {
    if (e.getMessage().contains("Schema version property is not set")) {
        throw new IllegalStateException("Misconfigured schema manager: set schemaVersionProperty", e);
    }
    throw e;
}

When it happens

Trigger: Any call to getSchemaVersion() (via dbVersion/schemaCheckVersion/schemaUpdate) when the schemaVersionProperty field is null — typically because a custom subclass or manually constructed ServiceSqlScriptBasedDbSchemaManager was created without calling setSchemaVersionProperty.

Common situations: Custom engine configuration wiring the schema manager by hand and omitting the schema-version property; copying a partial configuration from an older Flowable setup; subclassing the manager for a custom service module.

Understand the failure class

Background: "is required", "must be set", "missing required field": configuration validation errors across open-source libraries — this error's family across 36 libraries.

Related errors

• No flowable tables in DB. Set property "databaseSchemaUpdate
• Could not set database schema on connection
• Flowable database problem: ${errorMessage}
• couldn't get ${context} db schema version
• version mismatch: library version is '${engineVersion}', db

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