flowable/flowable-engine · error · FlowableIllegalArgumentException

Process instance id is null

Error message

Process instance id is null

What it means

Flowable's ExecutionQueryImpl.processInstanceId() validates its argument and throws FlowableIllegalArgumentException when the process instance id is null. The query API requires a concrete, non-null id to build the WHERE clause; a null would produce an invalid or unbounded query. The library fails fast at query-construction time rather than returning wrong or empty results.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ExecutionQueryImpl.java:299

    }

    @Override
    public ExecutionQuery processDefinitionEngineVersion(String processDefinitionEngineVersion) {
        if (processDefinitionEngineVersion == null) {
            throw new FlowableIllegalArgumentException("Process definition engine version is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionEngineVersion = processDefinitionEngineVersion;
        } else {
            this.processDefinitionEngineVersion = processDefinitionEngineVersion;
        }
        return this;
    }

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

    @Override
    public ExecutionQuery 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)

Solutions

1. Check the variable holding the id for null before building the query and return early or substitute a safe default
2. Trace where the id originates (e.g. execution/process instance lookup) and handle the not-found case instead of passing null through
3. If you intend to query by something else, use the appropriate filter (processInstanceBusinessKey, processDefinitionKey) instead of an id
4. Wrap the query building in try-catch for FlowableIllegalArgumentException if null inputs are legitimately possible

Example fix

// before
ExecutionQuery query = runtimeService.createExecutionQuery().processInstanceId(instanceId);
// after
if (instanceId == null) {
    throw new IllegalStateException("processInstanceId must be provided");
}
ExecutionQuery query = runtimeService.createExecutionQuery().processInstanceId(instanceId);

if (instanceId == null) {
    throw new IllegalArgumentException("instanceId must not be null before querying executions");
}

boolean hasProcessInstanceId(String id) {
    return id != null && !id.isBlank();
}

try {
    Execution exec = runtimeService.createExecutionQuery().processInstanceId(id).singleResult();
} catch (FlowableIllegalArgumentException e) {
    log.warn("Invalid execution query: {}", e.getMessage());
}

When it happens

Trigger: Calling runtimeService.createExecutionQuery().processInstanceId(null), typically when the id variable comes from an upstream lookup, a request parameter, or a method parameter that was never initialized.

Common situations: Passing a result of processInstance.getId() from a lookup that returned null (instance already completed/removed); wiring a REST path variable that is absent; refactoring where a variable was renamed but not assigned before the query.

Related errors

• rootScopeIds is null or empty
• parentScopeId is null
• parentScopeIds is null or empty
• Root process instance id is null
• Provided scope definitionid is null

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