{"record":{"id":"e6882a2e192fcf37","repo":"flowable/flowable-engine","slug":"post-upgrade-script-can-t-be-null","errorCode":null,"errorMessage":"Post upgrade script can't be null.","messagePattern":"Post upgrade script can't be null\\.","errorType":"validation","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationDocumentImpl.java","lineNumber":126,"sourceCode":"\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\n    public void setPostUpgradeScript(Script script) {\n        if (this.postUpgradeJavaDelegate == null && this.postUpgradeJavaDelegateExpression == null) {\n            if (script != null) {\n                this.postUpgradeScript = script;\n            } else {\n                throw new IllegalArgumentException(\"Post upgrade script can't be null.\");\n            }\n        } else {\n            throw new IllegalArgumentException(\"Post upgrade script can't be set when another post-upgrade task was already specified.\");\n        }\n    }\n\n    public void setPostUpgradeJavaDelegate(String javaDelegateClassName) {\n        if (this.postUpgradeScript == null && this.postUpgradeJavaDelegateExpression == null) {\n            if (StringUtils.isNotEmpty(javaDelegateClassName)) {\n                this.postUpgradeJavaDelegate = javaDelegateClassName;\n            } else {\n                throw new IllegalArgumentException(\"Post upgrade java delegate can't be empty or null.\");\n            }\n        } else {\n            throw new IllegalArgumentException(\"Post upgrade java delegate can't be set when another post-upgrade task was already specified.\");\n        }\n    }\n","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationDocumentImpl.java#L108-L144","documentation":"Flowable's ProcessInstanceMigrationDocument rejects a null post-upgrade Script. When building a migration document, calling setPostUpgradeScript to define a script executed after instance migration requires a non-null Script instance; the setter explicitly throws IllegalArgumentException otherwise, so a requested post-upgrade task is never silently ignored.","triggerScenarios":"Calling ProcessInstanceMigrationDocument.setPostUpgradeScript(script) with script == null while no postUpgradeJavaDelegate or postUpgradeJavaDelegateExpression has been set yet (i.e. via the builder's build path that routes to this setter).","commonSituations":"Conditionally building a Script (e.g. from optional config) and passing the null result; deserializing a migration document where the script element was absent; copy-pasting builder code and forgetting to instantiate the Script object.","solutions":["Ensure the Script instance is constructed before calling setPostUpgradeScript (e.g. new ScriptImpl(...)).","If no post-upgrade work is needed, do not call the setter at all instead of passing null.","If a delegate is more appropriate, use setPostUpgradeJavaDelegate or setPostUpgradeJavaDelegateExpression instead."],"exampleFix":"// before\nScript script = maybeGetScript(); // may return null\ndocument.setPostUpgradeScript(script);\n\n// after\nScript script = maybeGetScript();\nif (script != null) {\n    document.setPostUpgradeScript(script);\n}","handlingStrategy":"validation","validationCode":"if (script == null) { throw new IllegalArgumentException(\"script must be set before setPostUpgradeScript\"); }","typeGuard":"boolean isValidScript(Script s) { return s != null; }","tryCatchPattern":"try {\n    document.setPostUpgradeScript(script);\n} catch (IllegalArgumentException e) {\n    logger.error(\"Invalid post-upgrade script configuration\", e);\n}","preventionTips":["Null-check the Script before calling the setter","Only call the setter when a post-upgrade step is genuinely required","Set only one post-upgrade task kind (script, delegate, or expression)"],"tags":["java","flowable","validation","null-argument"],"backgroundTag":"null-argument","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"}