flowable/flowable-engine · error · FlowableIllegalArgumentException

parentProcessInstanceId is null

Error message

parentProcessInstanceId is null

What it means

HistoricCaseInstanceQueryImpl.parentProcessInstanceId(String) rejects a null parentProcessInstanceId. The value is stored as an equality filter over the parent process instance id of the historic case instance, and null is not a valid criterion, so FlowableIllegalArgumentException is thrown during query construction.

Solutions

1. Pass a non-null parent process instance id.
2. Only add the parentProcessInstanceId filter when the caller actually came from a process (guard with a null check).
3. For standalone case instances, use a query that does not filter on parent process instance at all.

Example fix

// before
query.parentProcessInstanceId(processInstanceId);
// after
if (processInstanceId != null) {
    query.parentProcessInstanceId(processInstanceId);
}

if (parentProcessInstanceId != null) {
    query.parentProcessInstanceId(parentProcessInstanceId);
}

boolean hasParentProcess(String id) { return id != null && !id.isEmpty(); }

try {
    query.parentProcessInstanceId(pid);
} catch (FlowableIllegalArgumentException e) {
    // case instance was not started from a process; drop the filter
}

When it happens

Trigger: Calling parentProcessInstanceId(null) on a HistoricCaseInstanceQuery, usually because the parent process instance id was fetched from an execution/variable that was null (e.g. the case instance was not started by a process).

Common situations: Correlating CMMN case instances with a calling BPMN process when the case was started standalone; passing entity.getId() of a parent that failed to load; REST payloads missing the parentProcessInstanceId field mapped straight into the query.

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/4e7a4b39f8870fce. Report an issue: GitHub.

Appendix: source

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

    }
    
    @Override
    public HistoricCaseInstanceQuery parentCaseInstanceId(String parentCaseInstanceId) {
        if (parentCaseInstanceId == null) {
            throw new FlowableIllegalArgumentException("parent case instance id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.parentCaseInstanceId = parentCaseInstanceId;
        } else {
            this.parentCaseInstanceId = parentCaseInstanceId;
        }
        return this;
    }

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

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

View on GitHub (pinned to d6d39ce1c6)