{"record":{"id":"5d8f6015930820bf","repo":"flowable/flowable-engine","slug":"error-while-executing-database-update-java-class","errorCode":null,"errorMessage":"error while executing database update java class '${upgradestepClassName}': ${e.getMessage()}","messagePattern":"error while executing database update java class '(.+?)': (.+?)","errorType":"exception","errorClass":"FlowableException","httpStatus":null,"severity":"critical","filePath":"modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/db/AbstractSqlScriptBasedDbSchemaManager.java","lineNumber":300,"sourceCode":"\n                    } else {\n                        logger.debug(line.substring(3));\n\n                    }\n\n                } else if (line.startsWith(\"execute java \")) {\n                    String upgradestepClassName = line.substring(13).trim();\n                    DbUpgradeStep dbUpgradeStep = null;\n                    try {\n                        dbUpgradeStep = (DbUpgradeStep) ReflectUtil.instantiate(upgradestepClassName);\n                    } catch (FlowableException e) {\n                        throw new FlowableException(\"database update java class '\" + upgradestepClassName + \"' can't be instantiated: \" + e.getMessage(), e);\n                    }\n                    try {\n                        logger.debug(\"executing upgrade step java class {}\", upgradestepClassName);\n                        dbUpgradeStep.execute();\n                    } catch (Exception e) {\n                        throw new FlowableException(\"error while executing database update java class '\" + upgradestepClassName + \"': \" + e.getMessage(), e);\n                    }\n\n                } else if (line.length() > 0) {\n\n                    if (\"oracle\".equals(databaseType) && line.startsWith(\"begin\")) {\n                        inOraclePlsqlBlock = true;\n                        sqlStatement = addSqlStatementPiece(sqlStatement, line);\n\n                    } else if ((line.endsWith(\";\") && !inOraclePlsqlBlock) || (line.startsWith(\"/\") && inOraclePlsqlBlock)) {\n\n                        if (inOraclePlsqlBlock) {\n                            inOraclePlsqlBlock = false;\n                        } else {\n                            sqlStatement = addSqlStatementPiece(sqlStatement, line.substring(0, line.length() - 1));\n                        }\n\n                        try (Statement jdbcStatement = connection.createStatement();) {\n","sourceCodeStart":282,"sourceCodeEnd":318,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/db/AbstractSqlScriptBasedDbSchemaManager.java#L282-L318","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before: jumping versions directly\nconfig.setDatabaseSchemaUpdate(\"6.3.0\"); // from 5.x schema\n// after: restore backup and upgrade step by step\n// 5.x -> 6.0 -> 6.3, with databaseSchemaUpdate=true at each hop","handlingStrategy":"try-catch","validationCode":"// back up the database before upgrade\n// mysqldump --single-transaction flowable > flowable_backup.sql","typeGuard":null,"tryCatchPattern":"try { engineCfg.buildProcessEngine(); } catch (FlowableException e) { if (e.getMessage().contains(\"error while executing database update java class\")) { restoreFromBackup(); } throw e; }","preventionTips":["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"],"tags":["schema-upgrade","database","migration"],"backgroundTag":"database-write-failed","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}