flowable/flowable-engine · error · FlowableIllegalArgumentException

extraValue is null

Error message

extraValue is null

What it means

PlanItemInstanceQueryImpl.planItemInstanceExtraValue(String) throws FlowableIllegalArgumentException with message "extraValue is null" when the extraValue argument is null. The extra value is an optional custom attribute on plan item instances, and the query setter rejects null rather than interpreting it as 'no filter'.

Solutions

1. Null-check extraValue and conditionally add the criterion
2. Treat 'instances without an extra value' as a separate query path instead of using null
3. Validate optional search inputs at the service boundary before mapping them into the query
4. Catch FlowableIllegalArgumentException around generic/dynamic query builders

Example fix

// before
query.planItemInstanceExtraValue(extraValue); // throws when null
// after
if (extraValue != null) {
    query.planItemInstanceExtraValue(extraValue);
}

if (extraValue != null) {
    query.planItemInstanceExtraValue(extraValue);
}

boolean hasExtraValue = extraValue != null;

try {
    query.planItemInstanceExtraValue(extraValue);
} catch (FlowableIllegalArgumentException e) {
    log.warn("extraValue was null, filter skipped");
}

When it happens

Trigger: Calling planItemInstanceExtraValue(null), commonly when the extra value was never set on the instance, or comes from an unset variable/property copied into the query.

Common situations: Custom application metadata stored in extraValue but absent on some instances; generic search forms forwarding an empty/optional field; reflective copying of instance properties into query criteria.

Related errors

• activatedBefore is null
• assignee is null
• availableAfter is null
• availableBefore is null
• before time is null

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

Appendix: source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/PlanItemInstanceQueryImpl.java:834

    }
    
    @Override
    public PlanItemInstanceQuery planItemInstanceFormKey(String formKey) {
        if (formKey == null) {
            throw new FlowableIllegalArgumentException("formKey is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.formKey = formKey;
        } else {
            this.formKey = formKey;
        }
        return this;
    }
    
    @Override
    public PlanItemInstanceQuery planItemInstanceExtraValue(String extraValue) {
        if (extraValue == null) {
            throw new FlowableIllegalArgumentException("extraValue is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.extraValue = extraValue;
        } else {
            this.extraValue = extraValue;
        }
        return this;
    }
    
    @Override
    public PlanItemInstanceQuery involvedUser(String involvedUser) {
        if (involvedUser == null) {
            throw new FlowableIllegalArgumentException("involvedUser is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.involvedUser = involvedUser;
        } else {
            this.involvedUser = involvedUser;

View on GitHub (pinned to d6d39ce1c6)