Activiti/Activiti · error · ActivitiIllegalArgumentException

Process definition version is null

Error message

Process definition version is null

What it means

ProcessInstanceQuery.processDefinitionVersion() throws ActivitiIllegalArgumentException when the version argument is null. Activiti validates query parameters eagerly so that malformed queries fail at construction time rather than producing an empty or invalid SQL query at execution time.

Solutions

1. Check that the version is non-null before calling processDefinitionVersion, or skip the filter when absent
2. Default the version (e.g. parse as int with a fallback) when the caller expects a value
3. If the query cannot proceed without a version, fail fast in your own code with a clear message

Example fix

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

if (version == null) { throw new IllegalArgumentException("processDefinitionVersion must be set before querying"); }
query.processDefinitionVersion(version);

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

try {
    query.processDefinitionVersion(version);
} catch (ActivitiIllegalArgumentException e) {
    logger.warn("Invalid version filter: {}", e.getMessage());
}

When it happens

Trigger: Calling runtimeService.createProcessInstanceQuery().processDefinitionVersion(null), e.g. when the version is read from an unvalidated request parameter or configuration and passed straight through.

Common situations: Building dynamic queries from HTTP query params or JSON bodies where the version field is optional and not defaulted; using Integer auto-unboxing from a null map/config value; upgrading code that previously omitted the filter.

Related errors

• Involved user is null
• key is null
• name is null
• Process definition id is null
• Process definition key is null

AI-assisted analysis of Activiti/Activiti@56435b1a97 (2026-09-09). Data as JSON: /api/errors/4497f319d730924a. Report an issue: GitHub.

Appendix: source

Thrown at activiti-core/activiti-engine/src/main/java/org/activiti/engine/impl/ProcessInstanceQueryImpl.java:224

    @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;
    }

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

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

View on GitHub (pinned to 56435b1a97)