{"record":{"id":"1fc9605177cc0831","repo":"flowable/flowable-engine","slug":"planitemdefinitionid-is-null","errorCode":null,"errorMessage":"planItemDefinitionId is null","messagePattern":"planItemDefinitionId is null","errorType":"exception","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/history/HistoricCaseInstanceQueryImpl.java","lineNumber":1056,"sourceCode":"    public HistoricCaseInstanceQuery includeCaseVariables() {\n        this.includeCaseVariables = true;\n        return this;\n    }\n\n    @Override\n    public HistoricCaseInstanceQuery includeCaseVariables(Collection<String> variableNames) {\n        if (variableNames == null || variableNames.isEmpty()) {\n            throw new FlowableIllegalArgumentException(\"variableNames is null or empty\");\n        }\n        includeCaseVariables();\n        this.variableNamesToInclude = new LinkedHashSet<>(variableNames);\n        return this;\n    }\n\n    @Override\n    public HistoricCaseInstanceQuery activePlanItemDefinitionId(String planItemDefinitionId) {\n        if (planItemDefinitionId == null) {\n            throw new FlowableIllegalArgumentException(\"planItemDefinitionId is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.activePlanItemDefinitionId = planItemDefinitionId;\n        } else {\n            this.activePlanItemDefinitionId = planItemDefinitionId;\n        }\n        return this;\n    }\n    \n    @Override\n    public HistoricCaseInstanceQuery activePlanItemDefinitionIds(Set<String> planItemDefinitionIds) {\n        if (planItemDefinitionIds == null) {\n            throw new FlowableIllegalArgumentException(\"planItemDefinitionIds is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.activePlanItemDefinitionIds = planItemDefinitionIds;\n        } else {\n            this.activePlanItemDefinitionIds = planItemDefinitionIds;","sourceCodeStart":1038,"sourceCodeEnd":1074,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/history/HistoricCaseInstanceQueryImpl.java#L1038-L1074","documentation":"HistoricCaseInstanceQueryImpl.activePlanItemDefinitionId(String) throws FlowableIllegalArgumentException when the plan item definition id is null. A null id cannot be used in the generated SQL predicate for filtering historic case instances by active plan item, so the library fails fast.","triggerScenarios":"Calling activePlanItemDefinitionId(null) on a HistoricCaseInstanceQuery, directly or inside an or() block (currentOrQueryObject), before executing the query.","commonSituations":"The plan item definition id is looked up from a model/config value that is missing; passing a variable that was never initialized; refactoring code where the id source was removed.","solutions":["Verify the plan item definition id is non-null before calling, e.g. Objects.requireNonNull(planItemDefinitionId, ...) at the call site.","Check the case model/repository actually contains the plan item definition and you copied the correct id.","If the value is optional, only add the filter when the id is present.","If multiple ids may apply, use activePlanItemDefinitionIds(Set) with a non-null set instead."],"exampleFix":"// before\nquery.activePlanItemDefinitionId(planItemDefinitionId); // may be null\n// after\nif (planItemDefinitionId != null) {\n    query.activePlanItemDefinitionId(planItemDefinitionId);\n}","handlingStrategy":"validation","validationCode":"if (planItemDefinitionId == null || planItemDefinitionId.isEmpty()) {\n    throw new IllegalArgumentException(\"planItemDefinitionId is required\");\n}\nquery.activePlanItemDefinitionId(planItemDefinitionId);","typeGuard":"boolean hasText(String s) {\n    return s != null && !s.trim().isEmpty();\n}","tryCatchPattern":"try {\n    query.activePlanItemDefinitionId(planItemDefinitionId);\n} catch (FlowableIllegalArgumentException e) {\n    if (\"planItemDefinitionId is null\".equals(e.getMessage())) {\n        // skip filter or rethrow with context\n    } else {\n        throw e;\n    }\n}","preventionTips":["Resolve plan item definition ids from the case model, not hard-coded strings","Guard optional id values before applying filters","Fail fast with a clear message at the call site","Only add active-plan-item filters when the id is actually known"],"tags":["java","flowable","cmmn","query","null-argument"],"backgroundTag":"null-argument","analyzedSha":"d6d39ce1c69ff244f2d9dc6af756a9b95e865586","analyzedAt":"2026-09-11T06:41:19.413Z","contentChangedAt":"2026-09-11T06:41:19.413Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}