{"record":{"id":"8befabe1c1ac4a86","repo":"flowable/flowable-engine","slug":"database-update-java-class-upgradestepclassname","errorCode":null,"errorMessage":"database update java class '${upgradestepClassName}' can't be instantiated: ${e.getMessage()}","messagePattern":"database update java class '(.+?)' can't be instantiated: (.+?)","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":294,"sourceCode":"\n                } else if (line.startsWith(\"-- \")) {\n\n                    if (\"-- force-commit\".equals(line)) {\n                        connection.commit();\n                        logger.debug(\"Forcing commit\");\n\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;","sourceCodeStart":276,"sourceCodeEnd":312,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/db/AbstractSqlScriptBasedDbSchemaManager.java#L276-L312","documentation":"When a schema script contains an 'execute java <class>' line, executeSchemaResource instantiates that class as a DbUpgradeStep via ReflectUtil. If instantiation fails (class missing, no public no-arg constructor, wrong type, static-init exception), it throws FlowableException wrapping the cause message.","triggerScenarios":"Running a database upgrade script containing an 'execute java' directive whose class cannot be found on the classpath or cannot be instantiated — e.g. during dbSchemaUpgrade between specific Flowable versions.","commonSituations":"Custom jars excluding internal upgrade classes; classpath conflicts with different Flowable versions; shading/relocation that renames upgrade step classes; upgrading from a very old version where referenced classes changed packages.","solutions":["Ensure the complete, matching-version flowable-engine jar (including internal db upgrade classes) is on the classpath.","Read the chained cause (ClassNotFoundException / ClassCastException / InstantiationException) and fix the specific classpath issue.","Avoid shading/relocating Flowable packages if you rely on its schema upgrade scripts.","Perform the upgrade step manually by running the SQL and updating the schema version property if the java step cannot run."],"exampleFix":"// before: shaded jar relocations exclude upgrade steps\n<relocations><relocation><pattern>org.flowable</pattern><shadedPattern>com.myapp.shaded.flowable</shadedPattern></relocation></relocations>\n// after: keep org.flowable unshaded so ReflectUtil can instantiate DbUpgradeStep classes\n<relocations/>","handlingStrategy":"try-catch","validationCode":"try { Class.forName(\"org.flowable.common.engine.impl.db.DbUpgradeStep\"); } catch (ClassNotFoundException e) { throw new IllegalStateException(\"Flowable internal db classes missing from classpath\"); }","typeGuard":null,"tryCatchPattern":"try { engineCfg.buildProcessEngine(); } catch (FlowableException e) { if (e.getMessage().contains(\"can't be instantiated\")) { log.error(\"Upgrade step class issue: {}\", e.getCause(), e.getCause()); } throw e; }","preventionTips":["Do not shade or relocate org.flowable packages","Ensure matching Flowable versions across all engine modules","Inspect the chained cause (ClassNotFoundException vs ClassCastException) to pinpoint the classpath issue"],"tags":["reflection","classpath","schema-upgrade","class-not-found"],"backgroundTag":"class-not-found","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}