flowable/flowable-engine · error · ActivitiIllegalArgumentException

Process instance id is null

Error message

Process instance id is null

What it means

ExecutionQueryImpl.processInstanceId throws ActivitiIllegalArgumentException when the processInstanceId argument is null. The query builder rejects null filter values so that the resulting query is always well-formed. Pass a real process instance id to filter on it.

Solutions

1. Ensure the process instance id is resolved to a non-null value before building the query
2. Skip adding the processInstanceId criterion when the id is unknown instead of passing null
3. Fail earlier in your own code with a clearer error if the id is required but missing

Example fix

// before
ExecutionQuery q = runtimeService.createExecutionQuery().processInstanceId(instanceId);
// after
if (instanceId == null) {
    throw new IllegalStateException("processInstanceId is required");
}
ExecutionQuery q = runtimeService.createExecutionQuery().processInstanceId(instanceId);

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

boolean hasId = processInstanceId != null && !processInstanceId.isEmpty();

try { q.processInstanceId(id); } catch (ActivitiIllegalArgumentException e) { respondBadRequest(e.getMessage()); }

When it happens

Trigger: Calling query.processInstanceId(id) with a null id, typically when the id came from an uninitialized variable, an empty API path variable, or a failed lookup.

Common situations: REST handlers forwarding path parameters that were never populated; code that resolved a process instance reference earlier and got null; refactors where the id variable was renamed and a different (null) variable is passed.

Related errors

• Business key is null
• Execution id is null
• Parent id is null
• Process definition keys is null
• Process definition version is null

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

Appendix: source

Thrown at modules/flowable5-engine/src/main/java/org/activiti/engine/impl/ExecutionQueryImpl.java:143

            throw new ActivitiIllegalArgumentException("Process definition name is null");
        }
        this.processDefinitionName = processDefinitionName;
        return this;
    }

    @Override
    public ExecutionQuery processDefinitionVersion(Integer processDefinitionVersion) {
        if (processDefinitionVersion == null) {
            throw new ActivitiIllegalArgumentException("Process definition version is null");
        }
        this.processDefinitionVersion = processDefinitionVersion;
        return this;
    }

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

    @Override
    public ExecutionQuery processInstanceBusinessKey(String businessKey) {
        if (businessKey == null) {
            throw new ActivitiIllegalArgumentException("Business key is null");
        }
        this.businessKey = businessKey;
        return this;
    }

    @Override
    public ExecutionQuery processInstanceBusinessKey(String processInstanceBusinessKey, boolean includeChildExecutions) {
        if (!includeChildExecutions) {
            return processInstanceBusinessKey(processInstanceBusinessKey);

View on GitHub (pinned to d6d39ce1c6)