{"record":{"id":"b01c95ca752df8a4","repo":"flowable/flowable-engine","slug":"provided-plan-item-instance-id-is-null-b01c95","errorCode":null,"errorMessage":"Provided plan item instance id is null","messagePattern":"Provided plan item instance id is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/SuspendedJobQueryImpl.java","lineNumber":360,"sourceCode":"    }\n\n    @Override\n    public SuspendedJobQueryImpl caseDefinitionKey(String caseDefinitionKey) {\n        if (caseDefinitionKey == null) {\n            throw new FlowableIllegalArgumentException(\"Provided case definition key is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.caseDefinitionKey = caseDefinitionKey;\n        } else {\n            this.caseDefinitionKey = caseDefinitionKey;\n        }\n        return this;\n    }\n    \n    @Override\n    public SuspendedJobQueryImpl planItemInstanceId(String planItemInstanceId) {\n        if (planItemInstanceId == null) {\n            throw new FlowableIllegalArgumentException(\"Provided plan item instance id is null\");\n        }\n        subScopeId(planItemInstanceId);\n        scopeType(ScopeTypes.CMMN);\n        return this;\n    }\n\n    @Override\n    public SuspendedJobQueryImpl correlationId(String correlationId) {\n        if (correlationId == null) {\n            throw new FlowableIllegalArgumentException(\"Provided correlationId is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.correlationId = correlationId;\n        } else {\n            this.correlationId = correlationId;\n        }\n        return this;\n    }","sourceCodeStart":342,"sourceCodeEnd":378,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-job-service/src/main/java/org/flowable/job/service/impl/SuspendedJobQueryImpl.java#L342-L378","documentation":"SuspendedJobQueryImpl.planItemInstanceId(String) throws FlowableIllegalArgumentException when the given planItemInstanceId is null. The Flowable query API validates required filter values eagerly at setter time so that malformed queries fail immediately rather than producing confusing empty results or SQL errors at query execution. A null plan item instance id is never a meaningful filter, so it is rejected outright.","triggerScenarios":"Calling new SuspendedJobQueryImpl(...).planItemInstanceId(null), or passing a variable/parameter that was never initialized (e.g. a CMMN plan item id resolved from a map or request param that is absent) directly into planItemInstanceId().","commonSituations":"Developers building dynamic suspended-job queries in CMMN scenarios where the plan item instance id comes from user input, a case instance lookup, or an optional API field; the value is null because the case/plan item was not yet created or the wrong key was used to look it up.","solutions":["Ensure the plan item instance id is resolved correctly before building the query (e.g. via a plan item instance lookup or runtime service call).","Guard the setter call: only call planItemInstanceId(...) when the id is non-null, otherwise omit the filter entirely.","If the id should always exist, fix upstream data flow so the variable holding the id is populated (check API payload, DB record, or process variable)."],"exampleFix":"// before\nquery.planItemInstanceId(request.getPlanItemInstanceId()); // NPE-ish throw when null\n// after\nString planItemInstanceId = request.getPlanItemInstanceId();\nif (planItemInstanceId != null) {\n    query.planItemInstanceId(planItemInstanceId);\n}","handlingStrategy":"validation","validationCode":"if (planItemInstanceId == null || planItemInstanceId.isEmpty()) {\n    throw new IllegalArgumentException(\"planItemInstanceId must be provided before querying suspended jobs\");\n}","typeGuard":"boolean hasPlanItemInstanceId(String id) { return id != null && !id.isEmpty(); }","tryCatchPattern":"try {\n    jobService.createSuspendedJobQuery().planItemInstanceId(id).singleResult();\n} catch (FlowableIllegalArgumentException e) {\n    // treat as 'no filter value provided' and fall back to a broader query\n}","preventionTips":["Validate the plan item instance id exists via the CMMN runtime service before filtering on it.","Make query-builder code conditional on non-null filter values.","Wrap id resolution in a helper that either returns a valid id or an Optional.empty() handled explicitly."],"tags":["flowable","query","null-check","cmmn","job-service"],"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"}