flowable/flowable-engine · error · FlowableIllegalArgumentException

definitionTenantId must not be null

Error message

definitionTenantId must not be null

What it means

The fluent method ChangeTenantIdBuilder.definitionTenantId(String) throws FlowableIllegalArgumentException when called with null. It restricts the tenant change to definitions with a specific tenant id, and null is not an accepted value for that filter.

Solutions

1. Only call definitionTenantId when you actually have a non-null definition tenant id
2. Default or guard the value before chaining
3. Omit the filter entirely if all definitions should be included

Example fix

// before
builder.definitionTenantId(definitionTenantId);
// after
if (definitionTenantId != null) {
    builder.definitionTenantId(definitionTenantId);
}

if (definitionTenantId != null) {
    builder.definitionTenantId(definitionTenantId);
}

try {
    builder.definitionTenantId(definitionTenantId);
} catch (FlowableIllegalArgumentException e) {
    logger.warn("Skipping definitionTenantId filter: {}", e.getMessage());
}

When it happens

Trigger: Chaining changeTenantId(...).definitionTenantId(null) where the definition tenant id variable is null or uninitialized.

Common situations: An optional filter value that the caller passes through without null-checking; refactoring removed a default value previously used.

Related errors

• caseInstanceId is null
• The target tenant id must not be null.
• variableName is null
• A process instance id is required, but the provided id '" +…
• A process instance id is required, but the provided id

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

Appendix: source

Thrown at modules/flowable-engine-common/src/main/java/org/flowable/common/engine/impl/tenant/ChangeTenantIdBuilderImpl.java:48

    public ChangeTenantIdBuilderImpl(String sourceTenantId, String targetTenantId, ChangeTenantIdManager changeTenantIdManager) {
        if (sourceTenantId == null) {
            throw new FlowableIllegalArgumentException("The source tenant id must not be null.");
        }
        if (targetTenantId == null) {
            throw new FlowableIllegalArgumentException("The target tenant id must not be null.");
        }
        this.sourceTenantId = sourceTenantId;
        this.targetTenantId = targetTenantId;
        if (sourceTenantId.equals(targetTenantId)) {
            throw new FlowableIllegalArgumentException("The source and the target tenant ids must be different.");
        }
        this.changeTenantIdManager = changeTenantIdManager;
    }

    @Override
    public ChangeTenantIdBuilder definitionTenantId(String definitionTenantId) {
        if (definitionTenantId == null) {
            throw new FlowableIllegalArgumentException("definitionTenantId must not be null");
        }
        this.definitionTenantId = definitionTenantId;
        return this;
    }

    @Override
    public ChangeTenantIdResult simulate() {
        return changeTenantIdManager.simulate(this);
    }

    @Override
    public ChangeTenantIdResult complete() {
        return changeTenantIdManager.complete(this);
    }

    public String getSourceTenantId() {
        return sourceTenantId;
    }

View on GitHub (pinned to d6d39ce1c6)