{"record":{"id":"977639b2b4b20ca0","repo":"flowable/flowable-engine","slug":"pre-upgrade-script-can-t-be-null","errorCode":null,"errorMessage":"Pre upgrade script can't be null.","messagePattern":"Pre 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":90,"sourceCode":"    }\n\n    public void setMigrateToProcessDefinition(String processDefinitionKey, Integer processDefinitionVersion) {\n        this.migrateToProcessDefinitionKey = processDefinitionKey;\n        this.migrateToProcessDefinitionVersion = processDefinitionVersion;\n    }\n\n    public void setMigrateToProcessDefinition(String processDefinitionKey, Integer processDefinitionVersion, String processDefinitionTenantId) {\n        this.migrateToProcessDefinitionKey = processDefinitionKey;\n        this.migrateToProcessDefinitionVersion = processDefinitionVersion;\n        this.migrateToProcessDefinitionTenantId = processDefinitionTenantId;\n    }\n\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","sourceCodeStart":72,"sourceCodeEnd":108,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationDocumentImpl.java#L72-L108","documentation":"ProcessInstanceMigrationDocumentImpl.setPreUpgradeScript enforces that exactly one pre-upgrade task (script, Java delegate, or delegate expression) is configured. When no other pre-upgrade task is set and the provided Script is null, there is nothing to assign, so it throws IllegalArgumentException.","triggerScenarios":"Calling setPreUpgradeScript(null) on a ProcessInstanceMigrationDocumentImpl — typically from build() when no preUpgradeScript was configured but the setter was invoked unconditionally.","commonSituations":"Programmatic document assembly that always calls the setter; JSON conversion mapping an absent/empty script element to null; refactoring that removed script construction but left the setter call.","solutions":["Only call setPreUpgradeScript when a non-null Script instance exists","Skip the setter entirely if no pre-upgrade script is needed","Guard the call: if (script != null) document.setPreUpgradeScript(script);"],"exampleFix":"// before\ndocument.setPreUpgradeScript(jsonScript); // may be null\n// after\nif (jsonScript != null) {\n    document.setPreUpgradeScript(jsonScript);\n}","handlingStrategy":"validation","validationCode":"if (script == null) { throw new IllegalArgumentException(\"preUpgradeScript required\"); } document.setPreUpgradeScript(script);","typeGuard":"boolean canSetPreUpgradeScript(ProcessInstanceMigrationDocumentImpl doc, Script s) {\n    return s != null;\n}","tryCatchPattern":"try {\n    document.setPreUpgradeScript(script);\n} catch (IllegalArgumentException e) {\n    log.warn(\"No pre-upgrade script configured: {}\", e.getMessage());\n}","preventionTips":["Only call the setter with a non-null Script","Use Optional/conditional logic when mapping JSON to the document","Keep one code path responsible for configuring pre-upgrade tasks"],"tags":["flowable","process-migration","null-argument","pre-upgrade"],"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"}