{"record":{"id":"47ef420c4331ce30","repo":"flowable/flowable-engine","slug":"plan-item-definition-id-is-null","errorCode":null,"errorMessage":"Plan item definition id is null","messagePattern":"Plan item definition id is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/PlanItemInstanceQueryImpl.java","lineNumber":219,"sourceCode":"    }\n    \n    @Override\n    public PlanItemInstanceQuery planItemInstanceElementId(String elementId) {\n        if (elementId == null) {\n            throw new FlowableIllegalArgumentException(\"Element id is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.elementId = elementId;\n        } else {\n            this.elementId = elementId;\n        }\n        return this;\n    }\n    \n    @Override\n    public PlanItemInstanceQuery planItemDefinitionId(String planItemDefinitionId) {\n        if (planItemDefinitionId == null) {\n            throw new FlowableIllegalArgumentException(\"Plan item definition id is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.planItemDefinitionId = planItemDefinitionId;\n        } else {\n            this.planItemDefinitionId = planItemDefinitionId;\n        }\n        return this;\n    }\n    \n    @Override\n    public PlanItemInstanceQuery planItemDefinitionType(String planItemDefinitionType) {\n        if (planItemDefinitionType == null) {\n            throw new FlowableIllegalArgumentException(\"Plan item definition type is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.planItemDefinitionType = planItemDefinitionType;\n        } else {\n            this.planItemDefinitionType = planItemDefinitionType;","sourceCodeStart":201,"sourceCodeEnd":237,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/PlanItemInstanceQueryImpl.java#L201-L237","documentation":"Flowable's PlanItemInstanceQuery.planItemDefinitionId() throws FlowableIllegalArgumentException when planItemDefinitionId is null. This filter selects plan item instances by their definition id (the id of the plan item definition in the CMMN model); null is rejected eagerly at query-build time.","triggerScenarios":"Calling planItemDefinitionId(null), usually when the definition id comes from an unresolved lookup (e.g. CmmnModel/PlanItemDefinition lookup by a wrong key), an empty configuration value, or a missing REST parameter.","commonSituations":"Report builders parameterized by plan item definition where the parameter is optional; model parsing code that fails to resolve the definition and returns null; version upgrades where definition ids/keys changed in the redesigned CMMN model.","solutions":["Pass a valid plan item definition id from the CMMN model (e.g. via CmmnModel.getPlanItem(id).getPlanItemDefinition().getId())","Skip the filter when the id is null instead of passing null","Fix the model/key resolution so the definition id is resolved before query construction"],"exampleFix":"// before\nquery.planItemDefinitionId(definitionId); // throws when definitionId == null\n\n// after\nif (definitionId != null) {\n    query.planItemDefinitionId(definitionId);\n}","handlingStrategy":"validation","validationCode":"if (planItemDefinitionId != null && !planItemDefinitionId.isBlank()) {\n    query.planItemDefinitionId(planItemDefinitionId);\n}","typeGuard":"boolean isPresent(String id) { return id != null && !id.isBlank(); }","tryCatchPattern":"try {\n    query.planItemDefinitionId(planItemDefinitionId);\n} catch (FlowableIllegalArgumentException e) {\n    throw new BadRequestException(\"planItemDefinitionId is required\", e);\n}","preventionTips":["Resolve plan item definition ids from the CmmnModel before building queries","Make optional definition filters conditional instead of passing null","Re-verify definition ids after model changes or Flowable version upgrades"],"tags":["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-18T11:17:12.947Z"}