flowable/flowable-engine · error · org.flowable.common.engine.api.FlowableIllegalArgumentException

processInstanceId is empty

Error message

processInstanceId is empty

What it means

InternalVariableInstanceQueryImpl.processInstanceId(String) throws FlowableIllegalArgumentException when the given processInstanceId is null or empty. Filtering variables by process instance requires a concrete id; blank input is rejected eagerly at query-build time instead of issuing a meaningless database query.

Solutions

1. Resolve a valid non-empty process instance id before building the query
2. Skip the query and return an empty result when no id is available
3. Validate the id at the entry point of your service (e.g. @NotBlank)

Example fix

// before
query.processInstanceId(processInstanceId); // throws when blank
// after
if (processInstanceId != null && !processInstanceId.isEmpty()) {
    query.processInstanceId(processInstanceId);
} else {
    return Collections.emptyList();
}

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

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

try { query.processInstanceId(pid); } catch (FlowableIllegalArgumentException e) { log.warn("Missing processInstanceId for variable query", e); return Collections.emptyList(); }

When it happens

Trigger: Calling processInstanceId(null) or processInstanceId("") — e.g. a process instance that was never started, an id read from an empty request parameter, or an unset field.

Common situations: Process id sourced from a form/HTTP parameter not yet filled; code running before the process instance is persisted; whitespace-only strings pass isEmpty and may return zero rows.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• executionId is empty
• None of the given process categories can be null
• scopeId is empty
• Task id list is null
• Task name list is null

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

Appendix: source

Thrown at modules/flowable-variable-service/src/main/java/org/flowable/variable/service/impl/InternalVariableInstanceQueryImpl.java:95

    }

    @Override
    public InternalVariableInstanceQuery taskIds(Collection<String> taskIds) {
        if (taskIds == null || taskIds.isEmpty()) {
            throw new FlowableIllegalArgumentException("taskIds is null or empty");
        }

        if (withoutTaskId) {
            throw new FlowableIllegalArgumentException("Cannot combine taskIds(Collection) with withoutTaskId() in the same query");
        }
        this.taskIds = taskIds;
        return this;
    }

    @Override
    public InternalVariableInstanceQuery processInstanceId(String processInstanceId) {
        if (StringUtils.isEmpty(processInstanceId)) {
            throw new FlowableIllegalArgumentException("processInstanceId is empty");
        }
        this.processInstanceId = processInstanceId;
        return this;
    }

    @Override
    public InternalVariableInstanceQuery executionId(String executionId) {
        if (StringUtils.isEmpty(executionId)) {
            throw new FlowableIllegalArgumentException("executionId is empty");
        }
        this.executionId = executionId;
        return this;
    }

    @Override
    public InternalVariableInstanceQuery executionIds(Collection<String> executionIds) {
        if (executionIds == null || executionIds.isEmpty()) {
            throw new FlowableIllegalArgumentException("executionIds is null or empty");

View on GitHub (pinned to d6d39ce1c6)