flowable/flowable-engine · error · IllegalArgumentException

Pre upgrade script can't be set when another pre-upgrade…

Error message

Pre upgrade script can't be set when another pre-upgrade task was already specified.

What it means

Only one pre-upgrade task may be configured per migration document. If a pre-upgrade Java delegate or delegate expression was already set, calling setPreUpgradeScript throws IllegalArgumentException because scripts and delegates are mutually exclusive.

Solutions

Choose exactly one pre-upgrade task: script, Java delegate class, or delegate expression
Remove the earlier setPreUpgradeJavaDelegate/setPreUpgradeJavaDelegateExpression call if the script is intended
Create separate ProcessInstanceMigrationDocument instances for unrelated configurations

Example fix

// before
document.setPreUpgradeJavaDelegate("com.acme.PreUpgrader");
document.setPreUpgradeScript(script);
// after
document.setPreUpgradeScript(script); // drop the conflicting delegate

Defensive patterns

Strategy: validation

Validate before calling

if (doc != null && (preDelegateSet || preExpressionSet)) {
    throw new IllegalStateException("Pre-upgrade task already set; script is mutually exclusive");
}

Try / catch

try {
    document.setPreUpgradeScript(script);
} catch (IllegalArgumentException e) {
    log.error("Conflicting pre-upgrade configuration: {}", e.getMessage());
    throw e;
}

Prevention

Decide the single pre-upgrade mechanism (script vs delegate vs expression) up front
Avoid merging migration config from multiple sources onto one document
Track which pre-upgrade setter has been called in your builder wrapper

When it happens

Trigger: Calling setPreUpgradeScript after setPreUpgradeJavaDelegate or setPreUpgradeJavaDelegateExpression on the same ProcessInstanceMigrationDocumentImpl.

Common situations: Combining settings from multiple config sources (JSON plus programmatic overrides); copy-paste code that sets both script and delegate; iterating over several upgrade definitions that each call a different setter on one shared document.

Related errors

AI-assisted analysis of flowable/flowable-engine@d6d39ce1c6 (2026-09-11). Data as JSON: /api/errors/e853be6cfcd6a585. Report an issue: GitHub.

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/migration/ProcessInstanceMigrationDocumentImpl.java:93

        this.migrateToProcessDefinitionKey = processDefinitionKey;
        this.migrateToProcessDefinitionVersion = processDefinitionVersion;
    }

    public void setMigrateToProcessDefinition(String processDefinitionKey, Integer processDefinitionVersion, String processDefinitionTenantId) {
        this.migrateToProcessDefinitionKey = processDefinitionKey;
        this.migrateToProcessDefinitionVersion = processDefinitionVersion;
        this.migrateToProcessDefinitionTenantId = processDefinitionTenantId;
    }

    public void setPreUpgradeScript(Script script) {
        if (this.preUpgradeJavaDelegate == null && this.preUpgradeJavaDelegateExpression == null) {
            if (script != null) {
                this.preUpgradeScript = script;
            } else {
                throw new IllegalArgumentException("Pre upgrade script can't be null.");
            }
        } else {
            throw new IllegalArgumentException("Pre upgrade script can't be set when another pre-upgrade task was already specified.");
        }
    }

    public void setPreUpgradeJavaDelegate(String javaDelegateClassName) {
        if (this.preUpgradeScript == null && this.preUpgradeJavaDelegateExpression == null) {
            if (StringUtils.isNotEmpty(javaDelegateClassName)) {
                this.preUpgradeJavaDelegate = javaDelegateClassName;
            } else {
                throw new IllegalArgumentException("Pre upgrade java delegate can't be empty or null.");
            }
        } else {
            throw new IllegalArgumentException("Pre upgrade java delegate can't be set when another pre-upgrade task was already specified.");
        }
    }

    public void setPreUpgradeJavaDelegateExpression(String expression) {
        if (this.preUpgradeScript == null && this.preUpgradeJavaDelegate == null) {
            if (StringUtils.isNotEmpty(expression)) {

View on GitHub (pinned to d6d39ce1c6)