flowable/flowable-engine · error · FlowableIllegalArgumentException

Provided process instance id is null

Error message

Provided process instance id is null

What it means

Flowable throws FlowableIllegalArgumentException from EventSubscriptionQueryImpl.processInstanceId when the processInstanceId() query builder method is called with a null argument. The query API rejects null IDs because a null filter is indistinguishable from 'not filtered at all', so instead of silently returning wrong results it fails fast. Pass a non-null process instance id string or skip the filter entirely.

Solutions

1. Check the id for null before calling processInstanceId and only add the filter when it is non-null
2. Fix the upstream source so the process instance id is actually populated (task.getProcessInstanceId(), execution id, etc.)
3. If you do not need the filter, omit the processInstanceId() call instead of passing null
4. If you own the calling code, wrap the query building in a guard that skips null filters

Example fix

// before
List<EventSubscription> subs = runtimeService.createEventSubscriptionQuery()
    .processInstanceId(procInstId)
    .list();

// after
EventSubscriptionQueryImpl q = (EventSubscriptionQueryImpl) runtimeService.createEventSubscriptionQuery();
if (procInstId != null) {
    q.processInstanceId(procInstId);
}
List<EventSubscription> subs = q.list();

if (processInstanceId == null) {
    throw new IllegalStateException("processInstanceId required before querying event subscriptions");
}
query.processInstanceId(processInstanceId);

if (id instanceof String && !((String) id).isEmpty()) { /* safe to filter */ }

try {
    query.processInstanceId(id).list();
} catch (FlowableIllegalArgumentException e) {
    // log and fall back to unfiltered query or empty result
}

When it happens

Trigger: Calling runtimeService.createEventSubscriptionQuery().processInstanceId(null) or adding .processInstanceId(null) inside an or() block; any code path where the id variable comes from an unpopulated execution, variable, or API response that is null.

Common situations: Chaining query filters from a request parameter or context object that was never set (e.g. no process instance associated with a task); refactoring code that used to have the id; calling processInstanceId before the instance has started.

Related errors

• categoryLike is null
• categoryNotEquals is null
• key is null
• keyLike is null
• name is null

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

Appendix: source

Thrown at modules/flowable-eventsubscription-service/src/main/java/org/flowable/eventsubscription/service/impl/EventSubscriptionQueryImpl.java:149

    @Override
    public EventSubscriptionQueryImpl executionId(String executionId) {
        if (executionId == null) {
            throw new FlowableIllegalArgumentException("Provided execution id is null");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.executionId = executionId;
        } else {
            this.executionId = executionId;
        }

        return this;
    }

    @Override
    public EventSubscriptionQueryImpl processInstanceId(String processInstanceId) {
        if (processInstanceId == null) {
            throw new FlowableIllegalArgumentException("Provided process instance id is null");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.processInstanceId = processInstanceId;
        } else {
            this.processInstanceId = processInstanceId;
        }

        return this;
    }
    
    @Override
    public EventSubscriptionQueryImpl withoutProcessInstanceId() {
        if (inOrStatement) {
            this.currentOrQueryObject.withoutProcessInstanceId = true;
        } else {
            this.withoutProcessInstanceId = true;
        }

View on GitHub (pinned to d6d39ce1c6)