flowable/flowable-engine · error · FlowableIllegalArgumentException

version must be positive

Error message

version must be positive

What it means

Flowable's ModelQueryImpl.modelVersion() validates that the requested model version is a positive integer before building the query. Model versions in the repository start at 1, so a version of 0 or a negative number can never match any persisted model. The library fails fast with FlowableIllegalArgumentException instead of issuing a query that would silently return no rows.

Source

Thrown at modules/flowable-engine/src/main/java/org/flowable/engine/impl/ModelQueryImpl.java:125

        this.nameLike = nameLike;
        return this;
    }

    @Override
    public ModelQuery modelKey(String key) {
        if (key == null) {
            throw new FlowableIllegalArgumentException("key is null");
        }
        this.key = key;
        return this;
    }

    @Override
    public ModelQueryImpl modelVersion(Integer version) {
        if (version == null) {
            throw new FlowableIllegalArgumentException("version is null");
        } else if (version <= 0) {
            throw new FlowableIllegalArgumentException("version must be positive");
        }
        this.version = version;
        return this;
    }

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

    @Override
    public ModelQuery deploymentId(String deploymentId) {
        if (deploymentId == null) {
            throw new FlowableIllegalArgumentException("DeploymentId is null");
        }
        this.deploymentId = deploymentId;
        return this;

View on GitHub (pinned to d6d39ce1c6)

Solutions

1. Pass a 1-based version number: modelVersion(1) for the first deployed version of a model.
2. If you want 'latest' instead of a fixed version, drop modelVersion() and use latest() on the query.
3. Guard the computed version before calling: if (v == null || v <= 0) handle/skip the query.
4. If the value comes from user input, validate it is a positive integer at the API boundary.

Example fix

// before
ModelQuery query = repositoryService.createModelQuery()
    .modelKey("myModel")
    .modelVersion(versionIndex); // 0-based index

// after
ModelQuery query = repositoryService.createModelQuery()
    .modelKey("myModel");
if (versionIndex > 0) {
    query.modelVersion(versionIndex); // versions are 1-based
} else {
    query.latest();
}

if (version == null || version <= 0) {
    throw new IllegalArgumentException("Model version must be a positive integer, got: " + version);
}
Model model = repositoryService.createModelQuery().modelKey(key).modelVersion(version).singleResult();

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

try {
    Model model = repositoryService.createModelQuery().modelKey(key).modelVersion(version).singleResult();
} catch (FlowableIllegalArgumentException e) {
    log.warn("Invalid model version {}: {}", version, e.getMessage());
    // fall back to latest() or return 400 to the caller
}

When it happens

Trigger: Calling ModelQuery.modelVersion(0) or modelVersion(-1) (or any Integer <= 0) on a ModelQuery obtained from ProcessEngine.getRepositoryService().createModelQuery(). Also occurs when the version comes from user input or configuration that was not normalized to 1-based numbering.

Common situations: Zero-based vs one-based version confusion (e.g. indexing an array of versions from 0), passing a sentinel value like 0 for 'unspecified', deserializing version from JSON where it defaulted to 0, or off-by-one arithmetic when picking the 'previous' version (version - 1 hitting 0 on the first version).

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

• Error retrieving app engine info
• Could not find an app definition with id '<appDefinitionId>
• No action found in request body.
• No deployment id available
• No resource name available

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