flowable/flowable-engine · error · ActivitiIllegalArgumentException

Process instance id is null

Error message

Process instance id is null

What it means

processInstanceId(id) sets a process-instance filter on the query, internally mapped to the execution id. It throws ActivitiIllegalArgumentException('Process instance id is null') when the id argument is null, since a null id cannot filter and would silently return wrong results.

Source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java:99

    // Unused, see dynamic query
    protected String activityId;
    protected List<EventSubscriptionQueryValue> eventSubscriptions;

    public ProcessInstanceQueryImpl() {
    }

    public ProcessInstanceQueryImpl(CommandContext commandContext) {
        super(commandContext);
    }

    public ProcessInstanceQueryImpl(CommandExecutor commandExecutor) {
        super(commandExecutor);
    }

    @Override
    public ProcessInstanceQueryImpl processInstanceId(String processInstanceId) {
        if (processInstanceId == null) {
            throw new ActivitiIllegalArgumentException("Process instance id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.executionId = processInstanceId;
        } else {
            this.executionId = processInstanceId;
        }
        return this;
    }

    @Override
    public ProcessInstanceQuery processInstanceIds(Set<String> processInstanceIds) {
        if (processInstanceIds == null) {
            throw new ActivitiIllegalArgumentException("Set of process instance ids is null");
        }
        if (processInstanceIds.isEmpty()) {
            throw new ActivitiIllegalArgumentException("Set of process instance ids is empty");
        }

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass the actual process instance id string obtained from the start/process call
2. Validate request input (400 Bad Request on missing id) before building the query
3. Check the upstream variable producing the id (failed start, lost message property)
4. Catch ActivitiIllegalArgumentException to return a meaningful client error

Example fix

// before
ProcessInstance pi = runtimeService.startProcessInstanceByKey("order");
historyService.createHistoricProcessInstanceQuery().processInstanceId(pi.getId()); // pi can be null
// after
if (pi != null) {
    historyService.createHistoricProcessInstanceQuery().processInstanceId(pi.getId());
}

if (processInstanceId == null || processInstanceId.isEmpty()) {
    throw new IllegalArgumentException("processInstanceId is required");
}
query.processInstanceId(processInstanceId);

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

try {
    query.processInstanceId(pid);
} catch (ActivitiIllegalArgumentException e) {
    throw new BadRequestException("processInstanceId parameter is mandatory");
}

When it happens

Trigger: Calling ProcessInstanceQuery.processInstanceId(null), e.g. from code following a runtimeService.startProcessInstance...() call whose returned instance was null, or from a request parameter that was never provided.

Common situations: REST endpoints taking a processInstanceId query/path parameter that the client omitted; jobs processing messages that lost the correlation id.

Related errors

• Set of process instance ids is null
• Deployment id is null
• deploymentName is null
• deploymentNameLike is null
• deploymentCategory is null

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