flowable/flowable-engine · error · ActivitiIllegalArgumentException

Provided process instance id is null

Error message

Provided process instance id is null

What it means

Thrown by EventSubscriptionQueryImpl.processInstanceId when a null process instance id is supplied as a query criterion. Like the other setters in this query class, it validates the argument eagerly and rejects null so that invalid queries surface immediately at build time with ActivitiIllegalArgumentException. The fix belongs in the calling code that supplies the id.

Solutions

1. Null-check the process instance id and only add the criterion when present
2. Ensure the caller actually has a started process instance and passes its getId() value
3. If filtering by process instance is optional, build the query conditionally
4. Validate request parameters upstream (controller/validation layer) before reaching the query API

Example fix

// before
EventSubscriptionQuery q = runtimeService.createEventSubscriptionQuery().processInstanceId(pid);
// after
EventSubscriptionQuery q = runtimeService.createEventSubscriptionQuery();
if (pid != null) {
    q = q.processInstanceId(pid);
}

if (processInstanceId == null) { throw new IllegalArgumentException("processInstanceId must be non-null before querying"); }
query.processInstanceId(processInstanceId);

boolean hasInstanceId(ProcessInstance pi) { return pi != null && pi.getId() != null; }

try {
    query.processInstanceId(pid);
} catch (org.activiti.engine.ActivitiIllegalArgumentException e) {
    // pid was null: ensure the process instance exists and was passed
}

When it happens

Trigger: Calling createEventSubscriptionQuery().processInstanceId(null), typically when the instance id comes from an optional ProcessInstance reference, a variable, or an external request parameter that is missing.

Common situations: REST/controller code passing an unset request parameter straight into the query; processInstanceId read from a variable that was never set; code after process end where the instance lookup returns null; copy-paste of query code without binding the actual id.

Related errors

• Provided activity id is null
• Provided event name is null
• Provided event subscription id is null
• Provided execution id is null
• activity tenant id is null

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/EventSubscriptionQueryImpl.java:73

    public EventSubscriptionQueryImpl eventName(String eventName) {
        if (eventName == null) {
            throw new ActivitiIllegalArgumentException("Provided event name is null");
        }
        this.eventName = eventName;
        return this;
    }

    public EventSubscriptionQueryImpl executionId(String executionId) {
        if (executionId == null) {
            throw new ActivitiIllegalArgumentException("Provided execution id is null");
        }
        this.executionId = executionId;
        return this;
    }

    public EventSubscriptionQueryImpl processInstanceId(String processInstanceId) {
        if (processInstanceId == null) {
            throw new ActivitiIllegalArgumentException("Provided process instance id is null");
        }
        this.processInstanceId = processInstanceId;
        return this;
    }

    public EventSubscriptionQueryImpl activityId(String activityId) {
        if (activityId == null) {
            throw new ActivitiIllegalArgumentException("Provided activity id is null");
        }
        this.activityId = activityId;
        return this;
    }

    public EventSubscriptionQueryImpl eventType(String eventType) {
        if (eventType == null) {
            throw new ActivitiIllegalArgumentException("Provided event type is null");
        }
        this.eventType = eventType;

View on GitHub (pinned to d6d39ce1c6)