flowable/flowable-engine · critical · FlowableException

error while executing database update java class '${upgrades

Error message

error while executing database update java class '${upgradestepClassName}': ${e.getMessage()}

What it means

After successfully instantiating a DbUpgradeStep from an 'execute java' script line, executeSchemaResource invokes dbUpgradeStep.execute(). Any exception thrown by the step's execution is wrapped in a FlowableException with the class name and original message. This signals that the programmatic part of the database upgrade failed mid-way.

Source

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

                    } else {
                        logger.debug(line.substring(3));

                    }

                } else if (line.startsWith("execute java ")) {
                    String upgradestepClassName = line.substring(13).trim();
                    DbUpgradeStep dbUpgradeStep = null;
                    try {
                        dbUpgradeStep = (DbUpgradeStep) ReflectUtil.instantiate(upgradestepClassName);
                    } catch (FlowableException e) {
                        throw new FlowableException("database update java class '" + upgradestepClassName + "' can't be instantiated: " + e.getMessage(), e);
                    }
                    try {
                        logger.debug("executing upgrade step java class {}", upgradestepClassName);
                        dbUpgradeStep.execute();
                    } catch (Exception e) {
                        throw new FlowableException("error while executing database update java class '" + upgradestepClassName + "': " + e.getMessage(), e);
                    }

                } else if (line.length() > 0) {

                    if ("oracle".equals(databaseType) && line.startsWith("begin")) {
                        inOraclePlsqlBlock = true;
                        sqlStatement = addSqlStatementPiece(sqlStatement, line);

                    } else if ((line.endsWith(";") && !inOraclePlsqlBlock) || (line.startsWith("/") && inOraclePlsqlBlock)) {

                        if (inOraclePlsqlBlock) {
                            inOraclePlsqlBlock = false;
                        } else {
                            sqlStatement = addSqlStatementPiece(sqlStatement, line.substring(0, line.length() - 1));
                        }

                        try (Statement jdbcStatement = connection.createStatement();) {

View on GitHub (pinned to d6d39ce1c6)

Solutions

Inspect the chained cause exception to find the exact failure inside the upgrade step (SQL error, bad data).
Fix or clean the offending data in the affected tables, then retry the upgrade from a backup.
Restore from backup and upgrade through intermediate Flowable versions rather than jumping several versions.
If the step fails on a known-bad edge case, execute its logic manually against the database and set the schema version property accordingly.

Example fix

// before: jumping versions directly
config.setDatabaseSchemaUpdate("6.3.0"); // from 5.x schema
// after: restore backup and upgrade step by step
// 5.x -> 6.0 -> 6.3, with databaseSchemaUpdate=true at each hop

Defensive patterns

Strategy: try-catch

Validate before calling

// back up the database before upgrade
// mysqldump --single-transaction flowable > flowable_backup.sql

Try / catch

try { engineCfg.buildProcessEngine(); } catch (FlowableException e) { if (e.getMessage().contains("error while executing database update java class")) { restoreFromBackup(); } throw e; }

Prevention

Always back up the database before schema upgrades
Upgrade through each intermediate Flowable version instead of skipping several
Review release notes for data-migration steps that may fail on legacy data
Resolve any data inconsistencies from previous interrupted upgrades before retrying

When it happens

Trigger: A versioned upgrade script containing 'execute java <class>' where the step class' execute() throws — e.g. data migration logic hitting invalid legacy data or a SQL failure during a Flowable version upgrade.

Common situations: Upgrading a database with legacy/corrupt data the upgrade step did not anticipate; interrupted earlier upgrades leaving inconsistent data; database-specific SQL incompatibilities inside the upgrade step.

Related errors

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