flowable/flowable-engine · error · IllegalArgumentException

Pre upgrade java delegate can't be set when another…

Error message

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

What it means

Only one pre-upgrade task is allowed. If a pre-upgrade script or delegate expression was already set, calling setPreUpgradeJavaDelegate throws IllegalArgumentException regardless of the delegate value.

Solutions

Keep exactly one of script / Java delegate / delegate expression per document
Remove the earlier setPreUpgradeScript or setPreUpgradeJavaDelegateExpression call
Use separate documents for separate configurations

Example fix

// before
document.setPreUpgradeScript(script);
document.setPreUpgradeJavaDelegate("com.acme.PreUpgrader");
// after
document.setPreUpgradeJavaDelegate("com.acme.PreUpgrader");

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try {
    document.setPreUpgradeJavaDelegate(delegateClass);
} catch (IllegalArgumentException e) {
    throw new IllegalStateException("Conflicting pre-upgrade configuration", e);
}

Prevention

Pick one pre-upgrade mechanism per migration document
Centralize pre-upgrade configuration in one builder method
Audit JSON + programmatic configuration for overlap

When it happens

Trigger: Calling setPreUpgradeJavaDelegate on a ProcessInstanceMigrationDocumentImpl where preUpgradeScript or preUpgradeJavaDelegateExpression is already non-null.

Common situations: Setting a script in JSON and a delegate programmatically; accumulating configuration from multiple sources onto one document; template code that sets several upgrade hooks.

Related errors

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

Appendix: source

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

            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)) {
                this.preUpgradeJavaDelegateExpression = expression;
            } else {
                throw new IllegalArgumentException("Pre upgrade expression can't be empty or null.");
            }
        } else {
            throw new IllegalArgumentException("Pre upgrade expression can't be set when another pre-upgrade task was already specified.");
        }
    }

    public void setPostUpgradeScript(Script script) {
        if (this.postUpgradeJavaDelegate == null && this.postUpgradeJavaDelegateExpression == null) {
            if (script != null) {

View on GitHub (pinned to d6d39ce1c6)