{"record":{"id":"8e8bf54adec62f2e","repo":"flowable/flowable-engine","slug":"version-must-be-positive-8e8bf5","errorCode":null,"errorMessage":"version must be positive","messagePattern":"version must be positive","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/ModelQueryImpl.java","lineNumber":125,"sourceCode":"        this.nameLike = nameLike;\n        return this;\n    }\n\n    @Override\n    public ModelQuery modelKey(String key) {\n        if (key == null) {\n            throw new FlowableIllegalArgumentException(\"key is null\");\n        }\n        this.key = key;\n        return this;\n    }\n\n    @Override\n    public ModelQueryImpl modelVersion(Integer version) {\n        if (version == null) {\n            throw new FlowableIllegalArgumentException(\"version is null\");\n        } else if (version <= 0) {\n            throw new FlowableIllegalArgumentException(\"version must be positive\");\n        }\n        this.version = version;\n        return this;\n    }\n\n    @Override\n    public ModelQuery latestVersion() {\n        this.latest = true;\n        return this;\n    }\n\n    @Override\n    public ModelQuery deploymentId(String deploymentId) {\n        if (deploymentId == null) {\n            throw new FlowableIllegalArgumentException(\"DeploymentId is null\");\n        }\n        this.deploymentId = deploymentId;\n        return this;","sourceCodeStart":107,"sourceCodeEnd":143,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/ModelQueryImpl.java#L107-L143","documentation":"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.","triggerScenarios":"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.","commonSituations":"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).","solutions":["Pass a 1-based version number: modelVersion(1) for the first deployed version of a model.","If you want 'latest' instead of a fixed version, drop modelVersion() and use latest() on the query.","Guard the computed version before calling: if (v == null || v <= 0) handle/skip the query.","If the value comes from user input, validate it is a positive integer at the API boundary."],"exampleFix":"// before\nModelQuery query = repositoryService.createModelQuery()\n    .modelKey(\"myModel\")\n    .modelVersion(versionIndex); // 0-based index\n\n// after\nModelQuery query = repositoryService.createModelQuery()\n    .modelKey(\"myModel\");\nif (versionIndex > 0) {\n    query.modelVersion(versionIndex); // versions are 1-based\n} else {\n    query.latest();\n}","handlingStrategy":"validation","validationCode":"if (version == null || version <= 0) {\n    throw new IllegalArgumentException(\"Model version must be a positive integer, got: \" + version);\n}\nModel model = repositoryService.createModelQuery().modelKey(key).modelVersion(version).singleResult();","typeGuard":"boolean isValidModelVersion(Integer v) {\n    return v != null && v > 0;\n}","tryCatchPattern":"try {\n    Model model = repositoryService.createModelQuery().modelKey(key).modelVersion(version).singleResult();\n} catch (FlowableIllegalArgumentException e) {\n    log.warn(\"Invalid model version {}: {}\", version, e.getMessage());\n    // fall back to latest() or return 400 to the caller\n}","preventionTips":["Remember Flowable model versions are 1-based, never 0-based.","Use latest() when you do not need a specific version.","Validate user-supplied versions at the API boundary with a positive-integer check.","Compute 'previous version' as version-1 only when version > 1."],"tags":["flowable","query-builder","validation","argument"],"backgroundTag":"invalid-argument-value","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T11:17:12.474Z"}