flowable/flowable-engine · error · FlowableIllegalArgumentException

referenceId is null

Error message

referenceId is null

What it means

HistoricCaseInstanceQueryImpl.caseInstanceReferenceId(String) throws when the referenceId argument is null. Reference id is a free-form correlation field stored on the case instance; as a query filter it must be a concrete non-null string, otherwise the builder raises FlowableIllegalArgumentException right away.

Solutions

1. Pass a non-null reference id string.
2. Conditionally add the reference-id filter only when the value is present.
3. Sanitize optional request parameters before passing them into the query builder.

Example fix

// before
query.caseInstanceReferenceId(request.getReferenceId()); // optional, may be null
// after
if (request.getReferenceId() != null) {
    query.caseInstanceReferenceId(request.getReferenceId());
}

if (referenceId != null) {
    query.caseInstanceReferenceId(referenceId);
}

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

try {
    query.caseInstanceReferenceId(refId);
} catch (FlowableIllegalArgumentException e) {
    throw new BadRequestException("referenceId must not be null", e);
}

When it happens

Trigger: Calling caseInstanceReferenceId(null) — typically the reference id came from an optional request parameter, message correlation payload, or variable lookup that was absent.

Common situations: REST endpoints where referenceId is an optional query parameter passed unfiltered into the query builder; copying reference data from a business object where the field was never set; migration scripts with incomplete data.

Related errors

• Business status is null
• callback type is null
• callbackIds is null or empty
• Case definition keys is null
• caseInstance tenant id is null

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

Appendix: source

Thrown at modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/history/HistoricCaseInstanceQueryImpl.java:806

            this.parentProcessInstanceId = parentProcessInstanceId;
        }
        return this;
    }

    @Override
    public HistoricCaseInstanceQuery withoutCaseInstanceCallbackId() {
        if (inOrStatement) {
            this.currentOrQueryObject.withoutCallbackId = true;
        } else {
            this.withoutCallbackId = true;
        }
        return this;
    }

    @Override
    public HistoricCaseInstanceQuery 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 HistoricCaseInstanceQuery caseInstanceReferenceType(String referenceType) {
        if (referenceType == null) {
            throw new FlowableIllegalArgumentException("referenceType is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.referenceType = referenceType;
        } else {
            this.referenceType = referenceType;

View on GitHub (pinned to d6d39ce1c6)