flowable/flowable-engine · error · IllegalArgumentException

Post upgrade java delegate can't be empty or null.

Error message

Post upgrade java delegate can't be empty or null.

What it means

setPostUpgradeJavaDelegate requires a non-empty class name for the JavaDelegate executed after migration. Flowable throws IllegalArgumentException when the string is null or blank, since a post-upgrade task must be meaningfully specified.

Source

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

    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)) {
                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.");
        }
    }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass the fully qualified delegate class name, e.g. "com.acme.MyPostUpgradeDelegate".
2. If no post-upgrade task is needed, omit the call entirely.
3. Use setPostUpgradeScript or setPostUpgradeJavaDelegateExpression for the other task types.

Example fix

// before
String delegateClass = properties.getProperty("postUpgradeDelegate"); // null
document.setPostUpgradeJavaDelegate(delegateClass);

// after
String delegateClass = properties.getProperty("postUpgradeDelegate");
if (delegateClass != null && !delegateClass.isBlank()) {
    document.setPostUpgradeJavaDelegate(delegateClass);
}

if (javaDelegateClassName == null || javaDelegateClassName.isBlank()) { throw new IllegalArgumentException("delegate class name required"); }

boolean isValidDelegateName(String s) { return s != null && !s.trim().isEmpty(); }

try {
    document.setPostUpgradeJavaDelegate(className);
} catch (IllegalArgumentException e) {
    logger.error("Post-upgrade delegate class name missing", e);
}

When it happens

Trigger: Calling setPostUpgradeJavaDelegate(null) or setPostUpgradeJavaDelegate("") (or whitespace) when no postUpgradeScript or postUpgradeJavaDelegateExpression is yet set on the migration document.

Common situations: Reading a class name from properties/env that is missing or empty; refactoring where a constant holding the class name became null; templated migration configs with unfilled placeholders.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• The case definition id is mandatory, but '' has been provide
• version must be positive
• text is null
• Error code must not be empty.
• The command is null

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