flowable/flowable-engine · error · ActivitiIllegalArgumentException

Process definition version is null

Error message

Process definition version is null

What it means

ExecutionQueryImpl.processDefinitionVersion throws ActivitiIllegalArgumentException when the version argument passed to processDefinitionVersion(Integer) is null. The query API validates that each filter criterion is non-null before storing it, so a null version would otherwise produce an invalid or ambiguous query. This is an eager fail-fast guard on the query builder.

Solutions

1. Ensure a non-null Integer version is passed; only call processDefinitionVersion when the value is present
2. If you intend to query any version, do not call processDefinitionVersion at all instead of passing null
3. Validate/trim the value at the source (config, request param) before building the query

Example fix

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

if (version != null) { query.processDefinitionVersion(version); }

boolean hasVersion = (version instanceof Integer);

try { query.processDefinitionVersion(v); } catch (ActivitiIllegalArgumentException e) { log.warn("Bad query argument: {}", e.getMessage()); }

When it happens

Trigger: Calling query.processDefinitionVersion(someVersion) where someVersion is null, e.g. a variable holding the version was never initialized or a method parameter was forwarded as null.

Common situations: Dynamic query building where the version comes from configuration or a request parameter that is optional/absent; mixing up version-latest semantics (should use processDefinitionVersion or latest() instead of null); deserializing a query spec from JSON with a missing version field.

Related errors

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

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

Appendix: source

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

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

    @Override
    public ExecutionQuery processDefinitionName(String processDefinitionName) {
        if (processDefinitionName == null) {
            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");

View on GitHub (pinned to d6d39ce1c6)