flowable/flowable-engine · error · FlowableIllegalArgumentException

Process definition engine version is null

Error message

Process definition engine version is null

What it means

FlowableIllegalArgumentException thrown by ExecutionQueryImpl.processDefinitionEngineVersion when the argument is null. The engine version filter (e.g. the Flowable engine version a definition targets) must be a non-null string; null is rejected at query-build time. Pass a value or omit the filter.

Solutions

1. Null-check and apply the filter only when the engine version is known.
2. Populate the engine-version value in your config or metadata source.
3. Use FlowableVersions.CURRENT_VERSION (or an explicit version constant) as a default.
4. Omit the filter if engine version should not constrain the query.

Example fix

// before
query.processDefinitionEngineVersion(cfg.getEngineVersion());

// after
if (cfg.getEngineVersion() != null) {
    query.processDefinitionEngineVersion(cfg.getEngineVersion());
}

if (engineVersion != null) { query.processDefinitionEngineVersion(engineVersion); }

boolean hasEngineVersion = engineVersion != null && !engineVersion.isEmpty();

try {
    query.processDefinitionEngineVersion(engineVersion);
} catch (FlowableIllegalArgumentException e) {
    log.warn("Null engine version filter skipped");
}

When it happens

Trigger: Calling executionQuery.processDefinitionEngineVersion(null), including when setting it on currentOrQueryObject inside an or-statement.

Common situations: Engine version read from configuration or a metadata table that is missing; upgrades/migrations where the engine-version field was not populated.

Related errors

• activatedBefore is null
• activity tenant id is null
• after time is null
• appsDefinitionIds is null
• assignee is null

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

Appendix: source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ExecutionQueryImpl.java:286

    }

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

    @Override
    public ExecutionQuery processDefinitionEngineVersion(String processDefinitionEngineVersion) {
        if (processDefinitionEngineVersion == null) {
            throw new FlowableIllegalArgumentException("Process definition engine version is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.processDefinitionEngineVersion = processDefinitionEngineVersion;
        } else {
            this.processDefinitionEngineVersion = processDefinitionEngineVersion;
        }
        return this;
    }

    @Override
    public ExecutionQueryImpl processInstanceId(String processInstanceId) {
        if (processInstanceId == null) {
            throw new FlowableIllegalArgumentException("Process instance id is null");
        }
        if (inOrStatement) {
            this.currentOrQueryObject.processInstanceId = processInstanceId;
        } else {
            this.processInstanceId = processInstanceId;

View on GitHub (pinned to d6d39ce1c6)