{"record":{"id":"65ff898cb81ab84f","repo":"flowable/flowable-engine","slug":"process-instance-id-is-null-65ff89","errorCode":null,"errorMessage":"Process instance id is null","messagePattern":"Process instance id is null","errorType":"validation","errorClass":"FlowableIllegalArgumentException","httpStatus":null,"severity":"error","filePath":"modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java","lineNumber":149,"sourceCode":"    protected String rootProcessInstanceId;\n\n    public ProcessInstanceQueryImpl() {\n    }\n\n    public ProcessInstanceQueryImpl(CommandContext commandContext, ProcessEngineConfigurationImpl processEngineConfiguration) {\n        super(commandContext, processEngineConfiguration.getVariableServiceConfiguration());\n        this.processEngineConfiguration = processEngineConfiguration;\n    }\n\n    public ProcessInstanceQueryImpl(CommandExecutor commandExecutor, ProcessEngineConfigurationImpl processEngineConfiguration) {\n        super(commandExecutor, processEngineConfiguration.getVariableServiceConfiguration());\n        this.processEngineConfiguration = processEngineConfiguration;\n    }\n\n    @Override\n    public ProcessInstanceQueryImpl processInstanceId(String processInstanceId) {\n        if (processInstanceId == null) {\n            throw new FlowableIllegalArgumentException(\"Process instance id is null\");\n        }\n        if (inOrStatement) {\n            this.currentOrQueryObject.executionId = processInstanceId;\n        } else {\n            this.executionId = processInstanceId;\n        }\n        return this;\n    }\n\n    @Override\n    public ProcessInstanceQuery processInstanceIds(Set<String> processInstanceIds) {\n        if (processInstanceIds == null) {\n            throw new FlowableIllegalArgumentException(\"Set of process instance ids is null\");\n        }\n        if (processInstanceIds.isEmpty()) {\n            throw new FlowableIllegalArgumentException(\"Set of process instance ids is empty\");\n        }\n","sourceCodeStart":131,"sourceCodeEnd":167,"githubUrl":"https://github.com/flowable/flowable-engine/blob/d6d39ce1c69ff244f2d9dc6af756a9b95e865586/modules/flowable-engine/src/main/java/org/flowable/engine/impl/ProcessInstanceQueryImpl.java#L131-L167","documentation":"ProcessInstanceQueryImpl.processInstanceId(String) filters runtime process instances by id (implemented as an executionId filter). Flowable throws FlowableIllegalArgumentException when the id is null because a null id cannot identify an instance; also supports OR-statement blocks by delegating to the current or-query object.","triggerScenarios":"Calling processInstanceQuery().processInstanceId(null), typically with an id taken from a path variable, request parameter, or variable that is null. (Note: null is assigned to executionId, so this effectively queries by execution id.)","commonSituations":"REST endpoints where the instance-id path parameter is missing; task forms storing no processInstanceId; variable lookups returning null before the instance started.","solutions":["Pass the actual process instance (execution) id string.","Guard the call: only add the filter when the id is non-null.","Validate request parameters at the API boundary (400 on missing id) before reaching the query."],"exampleFix":"// before\nreturn runtimeService.createProcessInstanceQuery().processInstanceId(id).singleResult();\n\n// after\nif (id == null || id.isBlank()) {\n    throw new BadRequestException(\"processInstanceId is required\");\n}\nreturn runtimeService.createProcessInstanceQuery().processInstanceId(id).singleResult();","handlingStrategy":"validation","validationCode":"if (processInstanceId == null || processInstanceId.isBlank()) { throw new BadRequestException(\"processInstanceId is required\"); }","typeGuard":null,"tryCatchPattern":"try { return query.processInstanceId(id).singleResult(); } catch (FlowableIllegalArgumentException e) { throw new BadRequestException(\"invalid process instance id\"); }","preventionTips":["Validate path/query parameters at the REST layer before touching the engine.","Guard optional filters: only call processInstanceId when the id is present.","Remember this filter is implemented via executionId — pass execution/instance ids, not business keys."],"tags":["java","flowable","query-builder","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-18T16:30:33.424Z"}