flowable/flowable-engine · error · IllegalArgumentException

Post upgrade script can't be set when another post-upgrade…

Error message

Post upgrade script can't be set when another post-upgrade task was already specified.

What it means

Only one post-upgrade task may be configured on a ProcessInstanceMigrationDocument: a script, a Java delegate class, or a delegate expression. If one is already set and setPostUpgradeScript is called again, Flowable throws this IllegalArgumentException to prevent ambiguous post-migration behavior.

Solutions

Set exactly one of setPostUpgradeScript / setPostUpgradeJavaDelegate / setPostUpgradeJavaDelegateExpression per migration document.
Check with getters (getPostUpgradeScript/getPostUpgradeJavaDelegate/getPostUpgradeJavaDelegateExpression) before setting.
Create a fresh ProcessInstanceMigrationDocument instead of reusing a configured one.

Example fix

// before
document.setPostUpgradeJavaDelegate("com.acme.FixDelegate");
document.setPostUpgradeScript(script);

// after
document.setPostUpgradeScript(script); // only one post-upgrade task

Defensive patterns

Strategy: validation

Validate before calling

if (document.getPostUpgradeJavaDelegate() != null || document.getPostUpgradeJavaDelegateExpression() != null) { throw new IllegalStateException("another post-upgrade task already configured"); }

Try / catch

try {
    document.setPostUpgradeScript(script);
} catch (IllegalArgumentException e) {
    logger.warn("Post-upgrade task already specified; skipping script", e);
}

Prevention

Choose one post-upgrade mechanism up front
Don't reuse a migration document builder across different configs
Guard with getters before each setter call

When it happens

Trigger: Calling setPostUpgradeScript(script) after setPostUpgradeJavaDelegate or setPostUpgradeJavaDelegateExpression has already been called on the same migration document.

Common situations: Reusing a builder/config object across migrations without clearing it; combining configuration sources (XML/programmatic) that each set a different post-upgrade task type.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

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

Appendix: source

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

            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) {
                this.postUpgradeScript = script;
            } else {
                throw new IllegalArgumentException("Post upgrade script can't be null.");
            }
        } else {
            throw new IllegalArgumentException("Post upgrade script can't be set when another post-upgrade task was already specified.");
        }
    }

    public void setPostUpgradeJavaDelegate(String javaDelegateClassName) {
        if (this.postUpgradeScript == null && this.postUpgradeJavaDelegateExpression == null) {
            if (StringUtils.isNotEmpty(javaDelegateClassName)) {
                this.postUpgradeJavaDelegate = javaDelegateClassName;
            } else {
                throw new IllegalArgumentException("Post upgrade java delegate can't be empty or null.");
            }
        } else {
            throw new IllegalArgumentException("Post upgrade java delegate can't be set when another post-upgrade task was already specified.");
        }
    }

    public void setPostUpgradeJavaDelegateExpression(String expression) {
        if (this.postUpgradeScript == null && this.postUpgradeJavaDelegate == null) {
            if (StringUtils.isNotEmpty(expression)) {

View on GitHub (pinned to d6d39ce1c6)