flowable/flowable-engine · error · FlowableIllegalArgumentException

Process instance id is null

Error message

Process instance id is null

What it means

ProcessInstanceQueryImpl.processInstanceId(String) filters runtime process instances by id (implemented as an executionId filter). Flowable throws FlowableIllegalArgumentException when the id is null because a null id cannot identify an instance; also supports OR-statement blocks by delegating to the current or-query object.

Solutions

1. Pass the actual process instance (execution) id string.
2. Guard the call: only add the filter when the id is non-null.
3. Validate request parameters at the API boundary (400 on missing id) before reaching the query.

Example fix

// before
return runtimeService.createProcessInstanceQuery().processInstanceId(id).singleResult();

// after
if (id == null || id.isBlank()) {
    throw new BadRequestException("processInstanceId is required");
}
return runtimeService.createProcessInstanceQuery().processInstanceId(id).singleResult();

if (processInstanceId == null || processInstanceId.isBlank()) { throw new BadRequestException("processInstanceId is required"); }

try { return query.processInstanceId(id).singleResult(); } catch (FlowableIllegalArgumentException e) { throw new BadRequestException("invalid process instance id"); }

When it happens

Trigger: Calling processInstanceQuery().processInstanceId(null), typically with an id taken from a path variable, request parameter, or variable that is null. (Note: null is assigned to executionId, so this effectively queries by execution id.)

Common situations: REST endpoints where the instance-id path parameter is missing; task forms storing no processInstanceId; variable lookups returning null before the instance started.

Related errors

• Set of process instance ids is null
• activatedBefore is null
• activity tenant id is null
• after time is null
• after time is null

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java:149

    protected String rootProcessInstanceId;

    public ProcessInstanceQueryImpl() {
    }

    public ProcessInstanceQueryImpl(CommandContext commandContext, ProcessEngineConfigurationImpl processEngineConfiguration) {
        super(commandContext, processEngineConfiguration.getVariableServiceConfiguration());
        this.processEngineConfiguration = processEngineConfiguration;
    }

    public ProcessInstanceQueryImpl(CommandExecutor commandExecutor, ProcessEngineConfigurationImpl processEngineConfiguration) {
        super(commandExecutor, processEngineConfiguration.getVariableServiceConfiguration());
        this.processEngineConfiguration = processEngineConfiguration;
    }

    @Override
    public ProcessInstanceQueryImpl processInstanceId(String processInstanceId) {
        if (processInstanceId == null) {
            throw new FlowableIllegalArgumentException("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 FlowableIllegalArgumentException("Set of process instance ids is null");
        }
        if (processInstanceIds.isEmpty()) {
            throw new FlowableIllegalArgumentException("Set of process instance ids is empty");
        }

View on GitHub (pinned to d6d39ce1c6)