flowable/flowable-engine · error · ActivitiIllegalArgumentException

Process definition version is null

Error message

Process definition version is null

What it means

ProcessInstanceQueryImpl.processDefinitionVersion(Integer) throws ActivitiIllegalArgumentException when the processDefinitionVersion argument is null. Since the parameter is the boxed Integer, a null unboxing scenario or unvalidated value is easy to hit; the API requires a concrete version number and rejects null at query build time. Use processDefinitionVersionGtThan/LessThan variants or omit the call for no filtering.

Source

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

    @Override
    public ProcessInstanceQuery processDefinitionName(String processDefinitionName) {
        if (processDefinitionName == null) {
            throw new ActivitiIllegalArgumentException("Process definition name is null");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionName = processDefinitionName;
        } else {
            this.processDefinitionName = processDefinitionName;
        }
        return this;
    }

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

        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionVersion = processDefinitionVersion;
        } else {
            this.processDefinitionVersion = processDefinitionVersion;
        }
        return this;
    }

    @Override
    public ProcessInstanceQueryImpl processDefinitionId(String processDefinitionId) {
        if (processDefinitionId == null) {
            throw new ActivitiIllegalArgumentException("Process definition id is null");
        }

        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionId = processDefinitionId;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Ensure the version is a concrete non-null Integer before calling (parse defensively with a default).
2. Skip the version filter when no version is specified.
3. Add validation on the parsed value (non-null, positive) before query construction.
4. Catch ActivitiIllegalArgumentException around query building for a clean validation error.

Example fix

// before
Integer version = parseVersion(request.getParameter("version"));
query.processDefinitionVersion(version);
// after
Integer version = parseVersion(request.getParameter("version"));
if (version != null) {
    query = query.processDefinitionVersion(version);
}

Integer version = raw == null || raw.isBlank() ? null : Integer.valueOf(raw);
if (version != null) {
    query = query.processDefinitionVersion(version);
}

boolean isValidVersion(Integer v) { return v != null && v > 0; }

try {
    result = query.processDefinitionVersion(version).list();
} catch (ActivitiIllegalArgumentException e) {
    if (e.getMessage().contains("Process definition version is null")) {
        throw new BadRequestException("version must be a valid integer");
    }
    throw e;
}

When it happens

Trigger: Calling .processDefinitionVersion(null) — commonly when the version is parsed from a string parameter (result may be null), or an Integer field on a filter DTO was never set.

Common situations: Integer.valueOf(requestParam) returning null on blank input; filter objects built from JSON where version was absent; copy-pasted code passing the wrong variable.

Related errors

• process instance tenant id is null
• Process definition category is null
• Process definition name is null
• Process definition id is null
• Set of process definition ids is null

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