flowable/flowable-engine · error · FlowableIllegalArgumentException

version must be positive

Error message

version must be positive

What it means

ProcessDefinitionQueryImpl.checkVersion validates the version passed to the processDefinitionVersion* filter methods. The Flowable engine throws FlowableIllegalArgumentException when the version is null or <= 0, because process definition versions are 1-based positive integers; a non-positive value would never match any deployed definition.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessDefinitionQueryImpl.java:256

    @Override
    public ProcessDefinitionQuery processDefinitionVersionLowerThan(Integer processDefinitionVersion) {
        checkVersion(processDefinitionVersion);
        this.versionLt = processDefinitionVersion;
        return this;
    }

    @Override
    public ProcessDefinitionQuery processDefinitionVersionLowerThanOrEquals(Integer processDefinitionVersion) {
        checkVersion(processDefinitionVersion);
        this.versionLte = processDefinitionVersion;
        return this;
    }

    protected void checkVersion(Integer version) {
        if (version == null) {
            throw new FlowableIllegalArgumentException("version is null");
        } else if (version <= 0) {
            throw new FlowableIllegalArgumentException("version must be positive");
        }
    }

    @Override
    public ProcessDefinitionQueryImpl latestVersion() {
        this.latest = true;
        return this;
    }

    @Override
    public ProcessDefinitionQuery active() {
        this.suspensionState = SuspensionState.ACTIVE;
        return this;
    }

    @Override
    public ProcessDefinitionQuery suspended() {
        this.suspensionState = SuspensionState.SUSPENDED;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a version >= 1 (versions are 1-based; the first deployment is version 1).
2. If you don't know the version, drop the version filter or use latestVersion() instead.
3. Null-check / range-check the value at the call site before building the query.

Example fix

// before
int v = config.getInt("def.version", 0);
ProcessDefinitionQuery q = repositoryService.createProcessDefinitionQuery().processDefinitionVersion(v);

// after
int v = config.getInt("def.version", 1);
if (v < 1) { v = 1; }
ProcessDefinitionQuery q = repositoryService.createProcessDefinitionQuery().processDefinitionVersion(v);

if (version == null || version < 1) { throw new IllegalArgumentException("version must be >= 1, got: " + version); }

try { query.processDefinitionVersion(version); } catch (FlowableIllegalArgumentException e) { log.warn("Invalid version filter: {}", e.getMessage()); throw new BadRequestException(e.getMessage()); }

When it happens

Trigger: Calling processDefinitionVersion(0), processDefinitionVersion(-1), processDefinitionVersion(null), or the GreaterThan/GreaterThanOrEquals/LowerThan/LowerThanOrEquals variants with a null or non-positive Integer.

Common situations: Computing a version from config or a database value that defaults to 0/null before a definition was ever deployed; off-by-one errors (treating versions as 0-based); passing an unboxed null from a map lookup keyed by a typo'd property name.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Cannot use taskIds together with excludeLocalVariables
• variableName is null
• caseInstanceId is null
• The case definition id is mandatory, but '' has been provide
• after time is null

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