flowable/flowable-engine · error · FlowableIllegalArgumentException

referenceType is null

Error message

referenceType is null

What it means

FlowableIllegalArgumentException thrown by CaseInstanceQueryImpl.caseInstanceReferenceType(String) when referenceType is null. Like referenceId, the reference type filter requires an explicit non-null value; null signals misuse of the query API. Provide a valid type string or skip the filter.

Solutions

1. Pass a non-null referenceType string.
2. Apply the filter conditionally when the value exists.
3. If filtering by referenceId only, drop the referenceType call.
4. Validate the DTO before query construction.

Example fix

// before
query.caseInstanceReferenceType(input.referenceType); // may be null
// after
if (input.referenceType != null) {
    query.caseInstanceReferenceType(input.referenceType);
}

if (referenceType != null) { query.caseInstanceReferenceType(referenceType); }

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

try { query.caseInstanceReferenceType(refType); } catch (FlowableIllegalArgumentException e) { log.warn("referenceType null: {}", e.getMessage()); }

When it happens

Trigger: Calling caseInstanceReferenceType(null) on a CaseInstanceQuery, e.g. when the type field of a request/DTO is absent.

Common situations: Pairing referenceId/referenceType filters where only one is provided by the caller; misconfigured start-form mappings leaving referenceType unset.

Related errors

• Business key is null
• Business status is null
• callbackIds is null or empty
• callbackType is null
• Case definition keys is null

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

Appendix: source

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

    }

    @Override
    public CaseInstanceQuery caseInstanceReferenceId(String referenceId) {
        if (referenceId == null) {
            throw new FlowableIllegalArgumentException("referenceId is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.referenceId = referenceId;
        } else {
            this.referenceId = referenceId;
        }
        return this;
    }

    @Override
    public CaseInstanceQuery caseInstanceReferenceType(String referenceType) {
        if (referenceType == null) {
            throw new FlowableIllegalArgumentException("referenceType is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.referenceType = referenceType;
        } else {
            this.referenceType = referenceType;
        }
        return this;
    }

    @Override
    public CaseInstanceQuery caseInstanceIsCompleteable() {
        if (inOrStatement) {
            this.currentOrQueryObject.completeable = true;
        } else {
            this.completeable = true;
        }
        return this;
    }

View on GitHub (pinned to d6d39ce1c6)