{"record":{"id":"9d03256a25281e2c","repo":"flowable/flowable-engine","slug":"pre-upgrade-java-delegate-can-t-be-empty-or-null","errorCode":null,"errorMessage":"Pre upgrade java delegate can't be empty or null.","messagePattern":"Pre upgrade java delegate can't be empty or null\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationDocumentImpl.java","lineNumber":102,"sourceCode":"\n    public void setPreUpgradeScript(Script script) {\n        if (this.preUpgradeJavaDelegate == null && this.preUpgradeJavaDelegateExpression == null) {\n            if (script != null) {\n                this.preUpgradeScript = script;\n            } else {\n                throw new IllegalArgumentException(\"Pre upgrade script can't be null.\");\n            }\n        } else {\n            throw new IllegalArgumentException(\"Pre upgrade script can't be set when another pre-upgrade task was already specified.\");\n        }\n    }\n\n    public void setPreUpgradeJavaDelegate(String javaDelegateClassName) {\n        if (this.preUpgradeScript == null && this.preUpgradeJavaDelegateExpression == null) {\n            if (StringUtils.isNotEmpty(javaDelegateClassName)) {\n                this.preUpgradeJavaDelegate = javaDelegateClassName;\n            } else {\n                throw new IllegalArgumentException(\"Pre upgrade java delegate can't be empty or null.\");\n            }\n        } else {\n            throw new IllegalArgumentException(\"Pre upgrade java delegate can't be set when another pre-upgrade task was already specified.\");\n        }\n    }\n\n    public void setPreUpgradeJavaDelegateExpression(String expression) {\n        if (this.preUpgradeScript == null && this.preUpgradeJavaDelegate == null) {\n            if (StringUtils.isNotEmpty(expression)) {\n                this.preUpgradeJavaDelegateExpression = expression;\n            } else {\n                throw new IllegalArgumentException(\"Pre upgrade expression can't be empty or null.\");\n            }\n        } else {\n            throw new IllegalArgumentException(\"Pre upgrade expression can't be set when another pre-upgrade task was already specified.\");\n        }\n    }\n","sourceCodeStart":84,"sourceCodeEnd":120,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationDocumentImpl.java#L84-L120","documentation":"setPreUpgradeJavaDelegate requires a non-empty delegate class name when no other pre-upgrade task is configured. Passing null or an empty string gives the document nothing to execute, so it throws IllegalArgumentException.","triggerScenarios":"Calling setPreUpgradeJavaDelegate(null) or setPreUpgradeJavaDelegate(\"\") on a ProcessInstanceMigrationDocumentImpl with no preUpgradeScript or preUpgradeJavaDelegateExpression set.","commonSituations":"Reading the delegate class name from config/JSON where the field is missing or blank; string concatenation producing an empty value; placeholder not substituted.","solutions":["Pass a fully qualified JavaDelegate class name, e.g. setPreUpgradeJavaDelegate(\"com.acme.MyPreUpgradeDelegate\")","Guard with StringUtils.isNotEmpty before calling","Skip the setter when no pre-upgrade delegate is needed"],"exampleFix":"// before\ndocument.setPreUpgradeJavaDelegate(config.get(\"preUpgradeDelegate\")); // may be empty\n// after\nif (StringUtils.isNotEmpty(config.get(\"preUpgradeDelegate\"))) {\n    document.setPreUpgradeJavaDelegate(config.get(\"preUpgradeDelegate\"));\n}","handlingStrategy":"validation","validationCode":"if (delegateClass == null || delegateClass.trim().isEmpty()) {\n    throw new IllegalArgumentException(\"preUpgradeJavaDelegate class name required\");\n}","typeGuard":"boolean hasText(String s) { return s != null && !s.trim().isEmpty(); }","tryCatchPattern":"try {\n    document.setPreUpgradeJavaDelegate(delegateClass);\n} catch (IllegalArgumentException e) {\n    log.warn(\"Skipping pre-upgrade delegate: {}\", e.getMessage());\n}","preventionTips":["Check config/JSON sources for blank values before mapping","Also verify the class exists on the classpath with Class.forName","Use hasText-style guards for all string-based settings"],"tags":["flowable","process-migration","empty-argument","pre-upgrade"],"backgroundTag":"empty-required-field","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-18T11:17:12.947Z"}