flowable/flowable-engine · error · IllegalArgumentException

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

Error message

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

What it means

This is the mutual-exclusion counterpart for the Java delegate: if a post-upgrade Script or delegate Expression is already configured, calling setPostUpgradeJavaDelegate throws IllegalArgumentException, because only one post-upgrade task can exist on the migration document.

Solutions

Configure exactly one post-upgrade task type per migration document.
Check the getters before calling the setter and skip if a task exists.
Instantiate a new migration document for each migration with distinct settings.

Example fix

// before
document.setPostUpgradeJavaDelegateExpression("${fixBean}");
document.setPostUpgradeJavaDelegate("com.acme.FixDelegate");

// after
document.setPostUpgradeJavaDelegateExpression("${fixBean}"); // single task only

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

try {
    document.setPostUpgradeJavaDelegate(className);
} catch (IllegalArgumentException e) {
    logger.warn("Another post-upgrade task already configured", e);
}

Prevention

Decide on a single post-upgrade strategy per migration
Avoid layering configs that both define post-upgrade tasks
Guard setter calls with getter checks

When it happens

Trigger: Calling setPostUpgradeJavaDelegate(className) after setPostUpgradeScript or setPostUpgradeJavaDelegateExpression has already been called on the same ProcessInstanceMigrationDocument.

Common situations: Merging migration configuration from multiple sources each specifying a different post-upgrade mechanism; reusing a configured document/builder across runs.

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/75a50c58cc33efbb. Report an issue: GitHub.

Appendix: source

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

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

    @Override
    public String getMigrateToProcessDefinitionId() {
        return migrateToProcessDefinitionId;

View on GitHub (pinned to d6d39ce1c6)