{"record":{"id":"3d170479d18f6dc5","repo":"flowable/flowable-engine","slug":"extravalue-is-null-3d1704","errorCode":null,"errorMessage":"extraValue is null","messagePattern":"extraValue 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":834,"sourceCode":"    }\n    \n    @Override\n    public PlanItemInstanceQuery planItemInstanceFormKey(String formKey) {\n        if (formKey == null) {\n            throw new FlowableIllegalArgumentException(\"formKey is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.formKey = formKey;\n        } else {\n            this.formKey = formKey;\n        }\n        return this;\n    }\n    \n    @Override\n    public PlanItemInstanceQuery planItemInstanceExtraValue(String extraValue) {\n        if (extraValue == null) {\n            throw new FlowableIllegalArgumentException(\"extraValue is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.extraValue = extraValue;\n        } else {\n            this.extraValue = extraValue;\n        }\n        return this;\n    }\n    \n    @Override\n    public PlanItemInstanceQuery involvedUser(String involvedUser) {\n        if (involvedUser == null) {\n            throw new FlowableIllegalArgumentException(\"involvedUser is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.involvedUser = involvedUser;\n        } else {\n            this.involvedUser = involvedUser;","sourceCodeStart":816,"sourceCodeEnd":852,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-cmmn-engine/src/main/java/org/flowable/cmmn/engine/impl/runtime/PlanItemInstanceQueryImpl.java#L816-L852","documentation":"PlanItemInstanceQueryImpl.planItemInstanceExtraValue(String) throws FlowableIllegalArgumentException with message \"extraValue is null\" when the extraValue argument is null. The extra value is an optional custom attribute on plan item instances, and the query setter rejects null rather than interpreting it as 'no filter'.","triggerScenarios":"Calling planItemInstanceExtraValue(null), commonly when the extra value was never set on the instance, or comes from an unset variable/property copied into the query.","commonSituations":"Custom application metadata stored in extraValue but absent on some instances; generic search forms forwarding an empty/optional field; reflective copying of instance properties into query criteria.","solutions":["Null-check extraValue and conditionally add the criterion","Treat 'instances without an extra value' as a separate query path instead of using null","Validate optional search inputs at the service boundary before mapping them into the query","Catch FlowableIllegalArgumentException around generic/dynamic query builders"],"exampleFix":"// before\nquery.planItemInstanceExtraValue(extraValue); // throws when null\n// after\nif (extraValue != null) {\n    query.planItemInstanceExtraValue(extraValue);\n}","handlingStrategy":"validation","validationCode":"if (extraValue != null) {\n    query.planItemInstanceExtraValue(extraValue);\n}","typeGuard":"boolean hasExtraValue = extraValue != null;","tryCatchPattern":"try {\n    query.planItemInstanceExtraValue(extraValue);\n} catch (FlowableIllegalArgumentException e) {\n    log.warn(\"extraValue was null, filter skipped\");\n}","preventionTips":["Extra values are optional custom attributes; always null-check before filtering","Handle empty optional search fields as absent filters","Make generic query builders add criteria conditionally"],"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"}